Chatbots for security and IT teams (Part 2): Microsoft Teams

In 2019, Security and IT Teams are finding it harder to source and retain talent, which is why many teams today are embracing remote workers and distributed teams. Communicating within and between remote teams is challenging, and many organizations are using communication tools like Slack and Microsoft Teams, and with them, chatbots, to improve communication and collaboration.

Chatbots blog series 

In Part 1 of the series, we examined how to set up a chatbot within Microsoft Teams. This chatbot received commands from users from within Teams and replied with details collected using Tines.

This tutorial will delve deeper into Microsoft Teams chatbots and examine how to send rich notifications using Cards. It will also explain how to use the Microsoft Graph API and this chatbot to proactively find and contact users within Microsoft Teams. You can use these proactive notifications to crowdsource and confirm frequent incidents of suspicious activity from users in your organization.

In part three, we’ll examine setting up chatbots within Slack which can both take commands and crowdsource information from users.

Microsoft Teams advanced chatbots 

This tutorial will build upon part 1 where we set up a chatbot within Microsoft Teams. If you haven’t followed the first tutorial, click here and follow the steps to create a working chatbot within Tines.

Sending cards within Microsoft Teams 

In our last tutorial, we learned how to send replies to users who sent messages to our chatbot. A quick way to make these notifications look more professional is to send cards. Adaptive Cards are a way for developers to exchange card content in a common and consistent way in bot communications.

Cards can come in several formats. One of the most common formats is Hero Cards which contain a large image, one or more buttons, and a small amount of text:

Another common format is Thumbnail Cards. Thumbnail Cards typically contain a single, small thumbnail image, some short text, and one or more buttons.

You can make cards as complicated or rich as you deem necessary, for example using a card like below. These cards are all available as templates within Tines.

Sending Messages Proactively to Users 

The next challenge is to send messages proactively to users within Microsoft Teams. There are many reasons why you might want to proactively contact a user, for example:

• Confirming suspicious activity with a user e.g. a login from an unusual IP

• Informing a security team of a high priority incident, or an IT team of a new ticket or request

• Confirming validity of sudo commands

• Validating change to user permissions

• Confirming installation of unrecognized software

• Processing approval permissions from managers and service owners for access requests

• Prompting users to take action before escalation of a ticket; to manage evidence etc.

‍In order to send a proactive message to a user in Microsoft Teams, you need two pieces of information – the tenant ID of the Microsoft Teams tenant; and the Microsoft Teams Member ID of the individual user.

The tenant ID is easy to find as you used it in part 1 to create the Tines Bot. It is also returned in any communication sent to or by the bot. It can also be found manually in the link “Get link to team” within Microsoft Teams.

The Member ID is the “ID” field in the responses when retrieving details about a Team using the Teams API. It is not to be confused with the “objectID” which is the userID used in Microsoft Graph API calls.

All conversations initiated by a user with a Bot include the Member ID of the user. This is how it’s possible to reply to a user when they proactively send a message to the Tines chatbot.

Finding a User ID Proactively 

Unfortunately, however, Microsoft Teams does not allow you to search for a user using an email address and retrieve this Member ID. According to Microsoft “This is intentional to prevent spambots within the bot framework”.

Fortunately, there are ways around this limitation. The most simple way is to fetch the team roster. If your organization has a team that all members of your organization are automatically members of then you can return all members of that team using the below command made by the Tines Bot.

You will need the teams “teamId” or “internalId” which you can find within the Microsoft Teams UI. It is the parameter with the format guid@thread.MStool in the URL below. https://teams.microsoft.com/l/team/{{internalID}}/conversations/… The Team ID is also sent in all communications to the Bot from the Team Chat within the Teams UI.

Using the data returned from the team roster, you can then filter on the user whose email address matches the email address of the user you are searching for.

An alternative solution is to use an external tool like DynamoDBto store the team roster details and, using Tines, search the table for the user id of the individual you want to contact.

Finding a Member ID using only an Email Address 

For the purpose of this blog, however, we’ll examine a worst-case scenario – one where you neither have a team in which all employees are members, nor do you want to use a lookup table to store this information. In this case, you can perform the following series of searches in Microsoft Graph to retrieve the user ID.

Finding a User and Team in Microsoft Graph

First, you can search for the user’s graph ID using the email address of the user. We’re taking the “user_email” value from a “receive_events” webhook.

{
  "url": "https://graph.microsoft.com/v1.0/users/{{.receive_events.user_email}}/",
  "method": "get",
  "content_type": "json",
  "headers": {
    "Authorization": "Bearer {% credential msgraph %}"
  }
}

Using the ID returned you can search for the teams they have joined.

{
  "url": "https://graph.microsoft.com/v1.0/users/{{.get_user_profile.body.id}}/joinedTeams",
  "method": "get",
  "content_type": "json",
  "headers": {
    "Authorization": "Bearer {% credential msgraph %}"
  }
}

Then you can retrieve details for one of those teams. The data returned will include the “internal ID” which acts as The Microsoft Teams ID for that team.

{
  "url": "https://graph.microsoft.com/v1.0/Teams/{{.get_joined_teams.body.value.first.id}}/",
  "method": "get",
  "content_type": "json",
  "headers": {
    "Authorization": "Bearer {% credential msgraph %}"
  }
}

Fetching the Team Roster in Microsoft Teams

You can then use your chatbot to get the team roster as above. This will return the members of that Team and their ID, which can be used to initiate a conversation with them.

{
  "url": "https://{{.serviceurl}}/v3/conversations/{{.get_team_details.body.internalId}}/members",
  "method": "get",
  "content_type": "json",
  "payload": {
 
  },
  "headers": {
    "Authorization": "Bearer {{.get_bearer_token_from_ms.body.access_token}}"
  }
}

As this team will likely have more than one member, you will have to filter on the member whose email address matches the user you wish to contact.

{
  "mode": "message_only",
  "userid": "{% for member in get_team_members.body %}{% if member.email == {{.receive_events.user_email}} %}{{member.id}}{% endif %}{% endfor %}"
}

You can then begin a conversation with that user, and send them cards like the below.

{
  "url": "https://{{.serviceurl}}/v3/conversations/",
  "method": "post",
  "content_type": "json",
  "payload": {
    "bot": {
      "id": "{{.botId}}",
      "name": "Tines Bot"
    },
    "members": [
      {
        "id": "{{.filter_on_useremail.userid}}"
      }
    ],
    "channelData": {
      "tenant": {
        "id": "{{.tenantId}}"
      }
    }
  },
  "headers": {
    "Authorization": "Bearer {{.get_bearer_token_from_ms.body.access_token}}"
  }
}

‍The last step is to send a notification to the user – this can be done very easily using templates from any of the cards above. You can include a prompt that will automatically take the next step – e.g. escalating to on-call, closing an incident, or locking an account. The prompt can also force a second-factor confirmation through Tines using a tool like DUO or Okta.

The complete Proactive chatbots Story looks like the above and can be downloaded from here.

The Story will need to be customized for your environment. It can be edited to include just details from below the “get bearer token from ms” Action if the team ID is known, or from below the “create conversation with user” if the user ID is known.

Congratulations – you’ve now set up a chatbot in Microsoft Teams that can send complex alerts to any user in your organization!

In Part 3 we’ll examine how to create a chatbot to send similar alerts in Slack.

‍

*Please note we recently updated our terminology. Our "agents" are now known as "Actions," but some visuals might not reflect this.*