Update Microsoft Sentinel VIP Users Watchlist from Azure AD group using playbooks

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:

• VIP Users: A list of user accounts/employees  that have high impact value in the organization.
• Terminated Employees: A list of user accounts/employees that have been, or are about to be, terminated.
• Service Accounts: A list of service accounts and their owners.
• Identity Correlation: A list of related user accounts that belong to the same person.
• High Value Assets: A list of devices, resources, or other assets that have critical value in the organization.
• Network Mapping: A list of IP subnets and their respective organizational contexts.

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.

 

Playbook

The playbook runs once per day, and does the following:

1. Initializes a group ID variable (string, static content).
2. Next, the playbook uses the Microsoft Graph APIs to get Azure AD group details and members.
3. For each user in the Azure AD group, the playbook will check if they are already in the VIP Users watchlist. If they are already in it, the playbook will skip the step.
4. If they are not in the watchlist, the playbook will add those users to the watchlist with either:
   1. Azure AD Object ID and User Principal Name data for Azure AD users, or
   2. Azure AD Object ID, User Principal Name, and SID data if the user is synced from on-prem AD.

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.

5. After the users are sent to the watchlist, the playbook will query and return all members of the VIP Users watchlist (if any users are added in the first four steps, they will be included in the next playbook run).
6. Then, it will check for each member to confirm that they are still a member of the Azure AD group.
7. If the user is not a member of the group, it will be deleted from the VIP Users watchlist

Let's go through the steps to prepare the environment for deployment and through deployment and enablement of the playbook.

 

Pre-requisites

To deploy this playbook, we have a few pre-requisites:

1. Create the VIP Users watchlist from a built-in template.
2. Create/update Azure AD VIP group.
3. Create a service principal to authorize Azure Monitor Logs connector.

 

Create the VIP Users watchlist from built-in template

1. Open your Microsoft Sentinel environment and from the right menu, click on the watchlist.
2. Click on 'Templates', choose 'VIP Users', and then select 'Create from template'.
3. You can use a CSV file from this link with a dummy user, or you can download the scheme by clicking on 'Download Scheme' and fill in with details of at least one real user.
4. After the CSV file is ready, click on 'Browse for files' and upload your CSV template (if you need to replace the file, just click on 'Reset').
5. Select 'Next: Review and Create' and then on 'Create'.

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. 

 

Create/update Azure AD VIP group

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:

1. Go to Azure AD portal (aad.portal.azure.com) and from 'All services' choose 'Groups'.
2. Click on 'New group' and fill in the data.
   1. Group type > Security.
   2. Group name > VIP Users (you can follow an internal naming convention, we need ID for later steps, not the name).
   3. Add members now or later in the process.
3. Click on 'Create'.

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.

 

 

Create a service principal to authorize Azure Monitor Logs connector

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:

1. In a new tab, go to 'aad.portal.azure.com' > 'Azure Active Directory' > 'App registrations' > New registration'.
2. Enter a name (e.g., LogAnalytics Reader SP) and click on 'Register'.
3. Once it is registered, you need to generate a secret. Go to 'Certificates & secrets' > 'New client secret'.
4. Enter a description (e.g., LogAnalytics Reader SP secret) and choose when this secret will expire. Note: After the secret expires, the service principal will not have the permission to query data, and the playbook will not work anymore!
5. Click on 'Add'. The secret will be generated, and you will need to copy the value of the secret. Note: The secret will be masked once you exit this view, and you will not have access to it. You can always delete and create a new one.

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:

1. Go to 'portal.azure.com', search and open 'Key vault'.
2. Choose an existing one or click on 'Create' to create the new Key Vault (if using the existing Key Vault, please go to step 6).
3. Choose your Resource Group and enter a Key Vault name (e.g., AzSentinelSecrets).
4. Click on 'Review + Create' and then click 'Create'.
5. Click on 'Go to resource' once the Key vault is deployed.
6. Go to 'Secrets' under 'Settings' and click on 'Generate/Import' in the 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.

1. Go to 'portal.azure.com' and then search and select 'Log Analytics Workspaces'.
2. Choose workspace where Sentinel is and then select 'Access control (IAM)'.
3. Click on 'Add' > 'Add role assignment'.
4. Choose as follows:
   1. Role > Log Analytics Reader.
   2. Select > search and select service principal you created (e.g., LogAnalytics Reader SP).

5. Click on ‘Save’.

 

Quick Deployment

Once you have finished the processes above, you can start deploying the playbook.

From GitHub:

1. Click on ‘Deploy to Azure’ and continue to step 6. below.

Using the JSON template file:

1. From the GitHub repository - link, download the file ‘azuredeploy.json’.
2. In a new tab, go to portal.azure.com and in search, enter and select ‘Deploy a custom template’.
    

   

3. Click on 'Build your own template in the editor' and then on 'Load file'.
4. Select downloaded template ('azuredeploy.json') and click 'Open'.
5. Click on 'Save'.

Now we need to enter details from the pre-requisite:

6. On the next screen, please enter your details (please make sure that data is correct, or the playbook will not work). 

   

   1. Log Analytics Workspace and Resource Group name are where your Log Analytics workspace is located (and Microsoft Sentinel).
   2. Azure AD Group ID is the Object ID we recorded when we created the Azure AD group.
7. Once you finished this, click on 'Review + Create', and when validation is finished, click on 'Create'.

 

Post-deployment

After deployment is finished, we need to do a few more steps before we enable and run the playbook.

1. Assign the Microsoft Sentinel Contributor permissions to the Logic App system-assigned managed identity.
2. Assign the Azure AD User Administrator permissions to the Logic App system-assigned managed identity.
3. Authorize the Azure Monitor Logs connector.
4. Enable the playbook.

 

Assign Microsoft Sentinel Contributor permission to the Logic App system-assigned managed identity

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.

1. Open playbook overview ('Microsoft Sentinel' > 'Automation' > 'Playbooks' > search and open 'Update-VIPUsers-Watchlist-from-AzureAD-Group').
2. Choose 'Identity' under 'Settings'. Make sure that 'Status' under 'System assigned' is 'On'.
3. Choose 'Azure role assignments' and then 'Add role assignment'.
4. Select as follows:
   1. 'Scope' > 'Resource group'.
   2. 'Subscription' > where Microsoft Sentinel is.
   3. 'Resource group' > where Microsoft Sentinel is.
   4. 'Role' > 'Microsoft Sentinel Contributor'.
5. Click on 'Save'.

Assign Azure AD User Administrator permission to Logic App system-assigned managed identity

The next permission that we need to assign to the managed identity is User Administrator from Azure AD.

1. Go to 'aad.portal.azure.com' > 'All services' > 'Azure Active Directory' > 'Roles and administrators'.
2. Search and select 'User Administrator'.
3. Click on 'Add assignments' and under 'Select member(s)' search and select 'Update-VIPUsers-Watchlist-from-AzureAD-Group', then click on 'Next'.
4. Enter justification if required and click on 'Assign'.

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

 

 

Authorize the Azure Monitor Logs  connector

Now when we have all needed permissions assigned, we need to authorize three connectors in our playbook.

1. Open playbook overview ('Microsoft Sentinel' > 'Automation' > 'Playbooks' > search and open 'Update-VIPUsers-Watchlist-from-AzureAD-Group').
2. Under 'Overview', click on 'Edit'.
3. Click on 'For each member of VIP Azure AD group' to expand and then on 'Connections'. Select 'Add new' and choose 'Connect with service principal'. Enter service principal details (Application ID, Tenant ID, Application Secret, and connection name). 
4. Collapse 'For each member of VIP Azure AD group' and click on 'Connections' below it. Now we can choose the same connection we created in step 1. Locate the Display name that shows the Connection name you enter in Step 1 and select it.

Enable the 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.

 

Troubleshooting

1. Make sure that all API permissions and user/application roles are assigned.
2. Make sure that Logic App connectors are authorized with correct identity
3. If using user identity, make sure that user has needed permissions

 

Customization

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.

Posted at https://sl.advdat.com/3qiZwb5https://sl.advdat.com/3qiZwb5