Last August, Watchlist built-in templates were announced in Public Preview as a new feature of Microsoft Sentinel. Data in watchlists can be correlated with analytics rules, viewed in the entity pages and investigation graphs as insights, leveraged for custom use cases such as tracking VIP or sensitive users and more.
Watchlist templates currently include:
If you would like to see the watchlist template scheme – the scheme can be found on this link.
More information about using the watchlists templates can be found here.
We recently published new watchlist APIs and Logic App watchlist actions, enabling companies to easier maintain watchlists and watchlist items. Now you can create a new watchlist, update the watchlist, get all watchlist items, etc.
All watchlist APIs - Watchlists - REST API (Azure Sentinel) | Microsoft Docs
All watchlist item APIs - Watchlist Items - REST API (Azure Sentinel) | Microsoft Docs
Soon, we will be publishing a new blog that will focus on watchlist APIs and their use cases.
In this blog, we will be focusing on VIP Users built-in template.
Note: You can use the logic described for VIP Users also for Terminated Employees template or any other template that can feed from Azure AD group members.
Many organizations manage their user groups by adding users to Azure AD groups, and it's common to find Azure AD groups with VIP users already populated. Why not utilize this list of users and populate our VIP Users built-in template? The playbook described in this blog is doing just that. It will sync the existing/new Azure AD VIP group members to the Microsoft Sentinel VIP Users watchlist.
The playbook runs once per day, and does the following:
This is the end of the first part, where you are syncing users from the Azure AD group to the VIP Users watchlist. You also want to see are all members of the watchlist still members of the Azure AD group.
Let's go through the steps to prepare the environment for deployment and through deployment and enablement of the playbook.
To deploy this playbook, we have a few pre-requisites:
You will need to wait a couple of minutes until the template saves data to Log Analytics.
To see is it saved, click on 'Watchlist' > 'My Watchlists' > 'VIP Users' > 'View in Log Analytics'.
Note: Watchlist cannot be empty at the any point or the watchlist template will have to be re-created.
If you already have an Azure AD group with VIP users, ensure that all users are added as members and record Azure AD group ID, which we will need to deploy the playbook.
If you don't have an Azure AD group with VIP users or want to use a new one, you have to create it:
Now you need to open your newly created group, and from 'Overview' you need to record 'Object Id', which you need in the deployment phase.
Note: Only group members are synced to the VIP Users watchlist.
Note: You can skip these steps if you want to authorize the Azure Monitor Logs connector with the user identity or if you already have service principal created. Important info is that the user/service principal authorizing connection must have at least 'Log Analytics Reader' permission. To understand the differences between user and service principal authorization, please read this blog.
To create a service principal and assign permission, please follow these steps:
You can choose to save the secret on a secure local space or, even better, save it to the Key Vault. Please note that the user must have, at least, permission to create a secret (e.g., 'Key Vault Secrets Officer').
Here are the instructions on how to create a Key Vault:
You now can have your secret saved on a secure space and can access it as needed to authorize an Azure Monitor Logs connector within the playbook. Service principal that you created, you can use for any playbook where you need to authorize Azure Monitor Logs connection.
Now we need to assign 'Log Analytics Reader' permissions to a service principal.
Once you have finished the processes above, you can start deploying the playbook.
From GitHub:
Using the JSON template file:
Now we need to enter details from the pre-requisite:
After deployment is finished, we need to do a few more steps before we enable and run the playbook.
You need to assign the Microsoft Sentinel Contributor permissions to the system-assigned managed identity. Note that the Microsoft Sentinel Reader or Microsoft Sentinel Responder roles don't have enough permissions because we need to update the watchlist.
The next permission that we need to assign to the managed identity is User Administrator from Azure AD.
Suppose you don't want to assign this permission to managed identity or have a policy that cannot assign an active admin role. In that case, we can use Microsoft Graph APIs to give needed permissions to managed identity.
List of Microsoft Graph APIs and permissions needed for each used API
Get group (GET /groups/{id})
Permissions: GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All
List members (GET /groups/{id}/members)
Permissions: GroupMember.Read.All, Group.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.Read.All
Get user (GET /users/{id | userPrincipalName})
Permissions: User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Check member groups (POST /groups/{id}/checkMemberGroups)
Permissions: GroupMember.Read.All, Group.Read.All, Directory.Read.All, Directory.ReadWrite.All
To assign these permissions, we need to use PowerShell. Open PowerShell as admin and connect to Azure AD - https://docs.microsoft.com/powershell/module/azuread/?view=azureadps-2.0#connect-to-your-directory
After login, run the following code replacing the managed identity object ID. You can find the managed identity object ID on the ‘Identity’ blade under ‘Settings’ for the Logic App.
$MIGuid = "<Enter your managed identity guid here>"
$MI = Get-AzureADServicePrincipal -ObjectId $MIGuid
$GraphAppId = "00000003-0000-0000-c000-000000000000"
$PermissionName1 = "User.Read.All"
$PermissionName2 = "User.ReadWrite.All"
$PermissionName3 = "GroupMember.ReadWrite.All"
$PermissionName4 = "GroupMember.Read.All"
$PermissionName5 = "Group.Read.All"
$PermissionName6 = "Directory.Read.All"
$PermissionName7 = "Group.ReadWrite.All"
$PermissionName8 = "Directory.ReadWrite.All"
$GraphServicePrincipal = Get-AzureADServicePrincipal -Filter "appId eq '$GraphAppId'"
$AppRole1 = $GraphServicePrincipal.AppRoles | Where-Object {$_.Value -eq $PermissionName1 -and $_.AllowedMemberTypes -contains "Application"}
New-AzureAdServiceAppRoleAssignment -ObjectId $MI.ObjectId -PrincipalId $MI.ObjectId `
-ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole1.Id
$AppRole2 = $GraphServicePrincipal.AppRoles | Where-Object {$_.Value -eq $PermissionName2 -and $_.AllowedMemberTypes -contains "Application"}
New-AzureAdServiceAppRoleAssignment -ObjectId $MI.ObjectId -PrincipalId $MI.ObjectId `
-ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole2.Id
$AppRole3 = $GraphServicePrincipal.AppRoles | Where-Object {$_.Value -eq $PermissionName3 -and $_.AllowedMemberTypes -contains "Application"}
New-AzureAdServiceAppRoleAssignment -ObjectId $MI.ObjectId -PrincipalId $MI.ObjectId `
-ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole3.Id
$AppRole4 = $GraphServicePrincipal.AppRoles | Where-Object {$_.Value -eq $PermissionName4 -and $_.AllowedMemberTypes -contains "Application"}
New-AzureAdServiceAppRoleAssignment -ObjectId $MI.ObjectId -PrincipalId $MI.ObjectId `
-ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole4.Id
$AppRole5 = $GraphServicePrincipal.AppRoles | Where-Object {$_.Value -eq $PermissionName5 -and $_.AllowedMemberTypes -contains "Application"}
New-AzureAdServiceAppRoleAssignment -ObjectId $MI.ObjectId -PrincipalId $MI.ObjectId `
-ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole5.Id
$AppRole6 = $GraphServicePrincipal.AppRoles | Where-Object {$_.Value -eq $PermissionName6 -and $_.AllowedMemberTypes -contains "Application"}
New-AzureAdServiceAppRoleAssignment -ObjectId $MI.ObjectId -PrincipalId $MI.ObjectId `
-ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole6.Id
$AppRole7 = $GraphServicePrincipal.AppRoles | Where-Object {$_.Value -eq $PermissionName7 -and $_.AllowedMemberTypes -contains "Application"}
New-AzureAdServiceAppRoleAssignment -ObjectId $MI.ObjectId -PrincipalId $MI.ObjectId `
-ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole7.Id
$AppRole8 = $GraphServicePrincipal.AppRoles | Where-Object {$_.Value -eq $PermissionName8 -and $_.AllowedMemberTypes -contains "Application"}
New-AzureAdServiceAppRoleAssignment -ObjectId $MI.ObjectId -PrincipalId $MI.ObjectId `
-ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole8.Id
Now when we have all needed permissions assigned, we need to authorize three connectors in our playbook.
The playbook is almost ready to run. We need to go back to the 'Overview' page of the playbook and select 'Enable'. After the playbook is enabled, it should run automatically. Refresh the browser and check run history. If the run has failed, please check the troubleshooting steps.
As mentioned at the beginning of the blog, you can use the logic described for VIP Users also for Terminated Employees template or any other Microsoft Sentinel watchlist that can feed from Azure AD group members.
You will need to change the watchlist alias in the Azure Monitor Logs connector query and column that you will use for comparison (if the column is different). If you check the VIP User query, the alias is VIPUsers (line 1), and the column is User Principal Name (line 2).
_GetWatchlist('VIPUsers')
| distinct ["User Principal Name"]
For Terminated Employees template, it would look like this. Note that the column can stay the same since User Principal Name is the column in Terminated Employees template.
_GetWatchlist('TerminatedEmployees')
| distinct ["User Principal Name"]
You will need to update JSON field ('Specify Watchlist Item fields') and watchlist alias ('Specify watchlist alias') in Microsoft Sentinel connector action 'Watchlists - Add a new watchlist item' to reflect columns and data of the new watchlist.
If you need additional data/fields from Azure AD groups, you will need to modify 'HTTP' and 'Parse JSON' actions.
To learn more about common scenarios using watchlists, please read this blog.
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.