In addition to being a Security Information and Event Management (SIEM) tool, Microsoft Sentinel is a Security Orchestration, Automation, and Response (SOAR) platform. Automation takes a few different forms in Microsoft Sentinel, from automation rules that centrally manage the automation of incident handling and response, to playbooks that run predetermined sequences of actions to provide powerful and flexible advanced automation to your threat response tasks.
In this blog we will be focusing on playbooks and understanding application programming interface (API) permissions, connections, and connectors in Microsoft Sentinel playbooks.
A playbook is a collection of response/remediation actions and logic that can be run from Microsoft Sentinel as a routine. It is based on workflows built in Azure Logic Apps which is a cloud service that helps you schedule, automate, and orchestrate tasks and workflows across systems throughout the enterprise. They are very powerful as they interact with Microsoft Sentinel features (they can update your incidents, update watchlists, etc.), and also with other Azure or Microsoft services and even third-party services. Whether you use out-of-the-box playbook connectors or the more generic HTTP connector, ultimately you will be interacting with various APIs.
When creating playbooks, solutions that we want to use to automate tasks need to have their own connector in Logic Apps (like Office 365 Outlook, Microsoft Sentinel, Microsoft Teams, Azure Monitor Logs…) or to have possibility to interact via API so that we can use the generic HTTP connector. As each connector needs to create an API connection to the solution and authorize it, if you are getting started with playbooks you may find it challenging to figure out what permissions are required. For example, our playbook templates on GitHub may come with multiple connections. When you first deploy a template, you may notice the playbook fails when you run it for the first time due to lack of permissions. In this blog post we will cover some of the main connectors you may encounter when you use Microsoft Sentinel playbooks, different methods to authenticate, as well as permissions you may require.
Before we move into specifics about identities and connectors, let’s quickly revisit the permissions needed to create and run a playbook in Logic Apps:
The first topic that we will cover are the type of identities you can use in a playbook to authorize a connection between Logic Apps and the solution of your choice. There are three types of identities:
A common challenge for developers is the management of secrets and credentials used to secure communication between different components making up a solution. Managed identities eliminate the need for developers to manage credentials. To enable managed identity on your Logic App, you need to go under Identity, and choose from:
After enabling a managed identity we have to assign appropriate permissions to it. If we use it with the Microsoft Sentinel connector, based on actions that connector will perform, we need to assign Microsoft Sentinel Reader, Microsoft Sentinel Responder, or Microsoft Sentinel Contributor role.
It is important to note that managed identity is in preview and is available only to the subset of connectors.
Note that there is hard limit of 2000 role assignments per subscription.
Managed identity is the recommended approach to authorize connections for playbooks. For more info about interaction between managed identity and playbooks, check this blog - What’s new: Managed Identity for Microsoft Sentinel Logic Apps connector - Microsoft Tech Community.
A service principal is an identity assigned when you register an application in the Azure AD. Click here to see instructions on how to create an app registration as well as how to get an Application ID, Tenant ID, and to generate a secret that you will need to authorize a Logic App connection with a service principal.
A service principal needs to have appropriate permissions to be able to perform a task. In the case of Azure Monitor Logs for example, we need to have Log Analytics Reader role-based access control (RBAC) assigned to the service principal.
Once you create a service principal you can use it on multiple playbooks: in our example, we used a service principal for Azure Monitor Logs and we can reuse that connection for each playbook where we have an Azure Monitor Logs connector.
Note: You must manage your service principal’s secret and store it to a secure place (e.g.. Key Vault). This adds additional admin work since you will need to keep track of your service principal secrets as well as their expiration date. If the service principal’s secret expires, connections made with that service principal will stop working, which could have an adverse effect on your security operations.
This is the most straightforward option in terms of identities, because you need to sign in with your user account or user account that has the required privileges. To use this, go to the Logic App and select API connections then select the API connection they want to authorize, select Edit API connection and select Authorize and Save.
Or you can sign in from the Logic App designer view, as seen in the below screenshot:
To successfully authorize a connection with a user identity, the user needs to have the appropriate license/permissions assigned to them. If we look at the Office 365 Outlook connector, the user needs to have an Exchange Online license assigned. If we want to use a user identity with Azure Monitor Logs connector then the user must have the Log Analytics Reader permission assigned to them.
Whilst this option is often the most convenient for users, there are downsides to using a user identity:
Now, let’s have a look at some of the main playbook connectors you will use for Microsoft Sentinel.
The Microsoft Sentinel connector can be used to trigger a playbook when an incident is created or with a manual trigger on the alert. The Microsoft Sentinel connector relies on the Microsoft Sentinel REST API and allows you to get incidents, update incidents, update watchlists, etc.
Once you have set up the connection you will notice that a new API connection has been created in the Logic App under API connections:
Sometimes you might need to connect to the Graph Security API. For example, you can use the Microsoft Graph Security API to import Threat Intelligence (TI) indicators into Microsoft Sentinel. If you want to add TI indicators to your Threatintelligence table, there is a connector that calls the Graph Security API to do this:
To find out which permissions you need, you should refer to the Graph API documentation, and for this specific example refer to tiIndicator: submitTiIndicators - Microsoft Graph beta | Microsoft Docs. On the Permissions section, you will see it requires ThreatIndicators.ReadWrite.OwnedBy.
Again, here you can connect with your user or with a managed identity:
This connector allows you to make a GET, PUT, POST, PATCH or DELETE API call to solutions that are supporting API connections. If you need to get specific information from the solution, and the connector is not available or the connector natively doesn’t support that action, while solutions support API calls, we can use an HTTP connector to get that data.
For example, since the Microsoft 365 Defender (M365D) connector does not synchronize comments, we can use an API GET call to ingest comments from M365D and update the Sentinel comment section with those values. In terms of permissions, what is required depends on the solution:
If you are using a service principal and want to save the secret in a secure place, the best practice is to store them in Key Vault. But what if we want to use this secret in our playbook for the HTTP connector explained above? In this scenario we have the Key Vault connector.
Options for connecting:
You can use a Key Vault action to get a secret and use that secret inside of the playbook.
One more option with the Key Vault connector also is to turn on Secure Inputs and Secure Outputs features.
With this feature on, when the playbook runs a Key Vault action, the input and output content will be hidden by default.
You will need to use the Azure Monitor Logs connector when you want to run a query against the data in your Microsoft Sentinel workspace from a Logic App. This can be used when we want to get more data about incident/alert entities before we decide what kind of action we will take. For example, we have a Watchlist with VIP users, and we want to cross-reference it with Accounts in the incident/alert. If the Account in the incident/alert is also in the Watchlist, then we will change the severity of the incident to High.
Options for connecting:
Here is the query in the Azure Monitor Logs Logic App connector:
Whenever you want to send an email notification, send an email approval, flag an email, forward an email etc., you can use the Office 365 Outlook connector.
Options for connecting:
There are different options to configure when using this connector e.g. add people to CC or BCC, add Attachment, configure the email address to use when replying, or change the importance of the email.
An important part of this connector to understand is the “From (Send As)” parameter. This is important because when you authorize a connection with the user identity, all emails will be sent from that account.
The “From (Send As)” parameter gives us the option to change from whom that email will be sent from to an Microsoft 365 Group, shared mailbox or some other user. Note that a valid Send As configuration must be applied to the mailbox so that it can send emails successfully.
Another option is to have one specific user account, like firstname.lastname@example.org, which you will use to authorize Office 365 Outlook connection and all emails will appear as if they are sent from email@example.com. Please note that the account used for this must be a user account (no Microsoft 365 Group or shared mailbox), and it must have a valid Exchange Online license/mailbox
Microsoft Teams is another popular connector that can be used for sending notifications. As Microsoft Teams plays a big role in organizing teams and providing a place to centralize collections of information and has become even more critical since the pandemic, it’s a useful tool to integrate into your SOC operations and automation.
Options for connecting:
Note that when a user authorizes a connection, all actions will appear as they are performed by that specific user. (Unlike with Office 365 Outlook where we have the “From (Send As)” parameter, that is not an option in Microsoft Teams.)
As mentioned with Office 365 Outlook connection, we can have one specific user account, like firstname.lastname@example.org, which you will use to authorize Microsoft Teams connection and all actions will appear as if they have been initiated by email@example.com.
Thanks to our reviewers @Jeremy Tan , @Inwafula and @Javier Soriano .
We hope you found this article useful, please leave us your feedback and questions in the comments section.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.