Understanding API connections for your Azure Sentinel Playbooks

This article is contributed. See the original author and article here.

In addition to being a Security Information and Event Management (SIEM) tool, Azure Sentinel is a Security Orchestration, Automation, and Response (SOAR) platform. Automation takes a few different forms in Azure 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 Azure Sentinel playbooks.

 

A playbook is a collection of response/remediation actions and logic that can be run from Azure 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 Azure 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, Azure 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 Azure 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:

• Permissions required to create a Logic App:
  
  
  
  • Logic App Contributor in the Resource Group (RG) where the Logic App has been created
  
  
  
  


• Permissions required to run a Logic App:
  
  
  
  • Azure Sentinel Responder in the RG where your Azure Sentinel workspace resides
  
  
  
  

• Permissions required for an Azure Sentinel automation rule to run a playbook:
  
  
  
  • Azure Sentinel Automation Contributor in the RG where the playbook to be triggered by the automation rule resides (these are explicit permissions for a special Azure Sentinel service account specifically authorized to trigger playbooks from automation rules. It is not meant for user accounts.)
  
  
  
  

 

Authorizing Connections

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:

1. Managed identity


2. Service principal


3. User identity

Managed Identity

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:

• A System assigned managed identity that turns your Logic App into an identity/service account to which you can provide permissions.


• A User-assigned managed identity which creates a separate Azure resource to which you can assign roles and permissions, and you can reuse on other Logic Apps.

After enabling a managed identity we have to assign appropriate permissions to it. If we use it with the Azure Sentinel connector, based on actions that connector will perform, we need to assign Azure Sentinel Reader, Azure Sentinel Responder, or Azure 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 Azure Sentinel Logic Apps connector – Microsoft Tech Community. 

 

Service principal 

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.  

 

User account 

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:

•  It is harder to audit what actions were taken by a user and what actions were taken by the playbook.


• If a user leaves the organization you need to update all the connections that use that identity to another user account.


•  If a user’s permissions or license changes  (e.g. they don’t use Exchange Online anymore or don’t have the Log Analytics Reader permissions anymore) you will need to update these connections to a user identity with the correct licensing/permissions.

 

Connectors

Now, let’s have a look at some of the main playbook connectors you will use for Azure Sentinel.

 

Azure Sentinel

The Azure Sentinel connector can be used to trigger a playbook when an incident is created or with a manual trigger on the alert. The Azure Sentinel connector relies on the Azure Sentinel REST API and allows you to get incidents, update incidents, update watchlists, etc.

 

Connection options:

• Managed identity (Recommended)


• Service Principal


• User identity

Other prerequisites:

• Azure Sentinel Reader role (if you only want to get information from an incident e.g., Get Entities)


• Azure Sentinel Operator role (if you want to update an incident); or


• Azure Sentinel Contributor role (if you want to make changes on your workspace e.g., update a watchlist).

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:

 

Microsoft Graph Security

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 Azure 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:

 

• Managed identity: this option is in preview and for now it is not possible to assign the required Graph API permission through the portal. If you want to choose this type of connection, you can assign the permission with PowerShell. If you want to explore this workaround, you can have a look at the personal blog “Rahul Nath” for instructions.  


• Signing in with a user: this is the most straightforward option, but there are some downsides as explained earlier in the blog. Unless your user is allowed to establish a connection, you will need a Security Administrator or Global Administrator to authorize it. This can be done in Logic Apps under API Connections, and then Edit API connection

 

HTTP connector

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:

• Microsoft Graph API: to understand the right permissions, please check the Microsoft Graph API section in this article:
  
  
  
  • Managed identity: Please check the Managed identity under the Microsoft Graph API section.
  
  
  • Active Directory OAuth: If your endpoint is the Microsoft Graph API, you can find instructions here.
  
  
  
  


• The http://management.azure.com audience: If your endpoint is part of http://management.azure.com, you will have to assign the right permissions for the endpoint you want to call. Let’s imagine you want to create a watchlist using REST API Manage watchlists in Azure Sentinel using REST API | Microsoft Docs. In this case, the endpoint is https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.OperationalInsights/workspaces/{{workspaceName}}/providers/Microsoft.SecurityInsights/watchlists/{{watchlistAlias}}?api-version={{api-version}} and the permission required would be Azure Sentinel Contributor. Knowing the permission you need will require some basic knowledge of the service.
  
  
  
  • Managed identity: you will assign the right role to the managed identity itself; you can do it from the Access control (IAM) on the resource for which you want to provide permission.
  
  
  • Active Directory OAuth: in this case, you will assign the permission on the app registration itself.
  
  
  
  

 

Key Vault

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:

• Managed identity (Recommended)


• Service Principal


• User identity

Other prerequisites:

• Managed identity/service principal/user identity authorizing the connection must have assigned permissions to read the secret (Key Vault Secrets User to read; Key Vault Secrets Officer to manage). Instructions to assign these permissions can be found by clicking on this link.

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.

 

Azure Monitor Logs

You will need to use the Azure Monitor Logs connector when you want to run a query against the data in your Azure 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:

• Service principal (recommended)


• User identity

Other prerequisites:

• Service principal/user identity authorizing connection must have the Log Analytics Reader role assigned

Here is the query in the Azure Monitor Logs Logic App connector:

 

Office 365 Outlook

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:

• User identity

Other prerequisites:

• User authorizing connection must have an Exchange Online license assigned

 

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 soc@xyz.com, which you will use to authorize Office 365 Outlook connection and all emails will appear as if they are sent from soc@xyz.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

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:

• User identity

Other prerequisites:

• User authorizing connection must have a Microsoft Teams license assigned, and


• Specific permissions (to post a message to a channel, the user must be a member of that team; to add a member – must be owner; to create a new team group – must have permission to create a Microsoft 365 Group…)

 

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 soc@xyz.com, which you will use to authorize Microsoft Teams connection and all actions will appear as if they have been initiated by soc@xyz.com.

 

Thanks to our reviewers @Jeremy Tan , @Innocent Wafula and @Javier Soriano .

 

We hope you found this article useful, please leave us your feedback and questions in the comments section.

 

Brought to you by Dr. Ware, Microsoft Office 365 Silver Partner, Charleston SC.