Device tagging in MDE by PowerShell (CSV)
top of page
Search

Device tagging in MDE by PowerShell (CSV)

In this blog, I will take you through device tagging in MDE using PowerShell, as I explained in my previous blogs of device Tagging Part 1 and Part 2 this solution makes it easier to tag devices.


First of all, we need to register an API App in Azure AD to grant permission to use API calls to MDE this is a prerequisite to tag devices using PowerShell


Step 1: Log in to Azure Ad Portal Link navigate to App Registration under Manage to click on New Registration this will take you through the app registration in the azure ad.



Step 2: Enter the app name in my case I had provided MDE_api as the app name, you can provide it as per your standards and select the supported account types in my case I had selected Accounts in this organizational directory only (Anand Nair only - Single-tenant) because I am using this app only for users and guest users in my tenant. Tap on Register to complete the app registration 



What are the differences between supported account types?

Accounts in this organizational directory only (Single tenant)

All user and guest accounts in your directory can use your application or API.

Use this option if your target audience is internal to your organization.

Accounts in any organizational directory (Any Azure AD directory - Multitenant)

All users with a work or school account from Microsoft can use your application or API. This includes schools and businesses that use Office 365.

Use this option if your target audience is business or educational customers and to enable multitenancy.

Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g., Skype, Xbox)

All users with a work or school, or personal Microsoft account can use your application or API. It includes schools and businesses that use Office 365 as well as personal accounts that are used to sign into services like Xbox and Skype.

Use this option to target the widest set of Microsoft identities and to enable multitenancy.

Personal Microsoft accounts only

Personal accounts that are used to sign into services like Xbox and Skype.

Use this option to target the widest set of Microsoft identities.

The app is being created with a display name as MDE_api and you can see application ID, Object ID, and Tenant ID.



Step 3:Once the app is registered next part is to assign API permission to Microsoft Defender for Endpoint for that navigate to API Permissions and tap on Add a permission



Select APIs my organization uses and search for WindowsDefenderATP and select WindowsDefenderATP



and select Application Permission and it will take to select the permission to expand the Machine option under Select Permission



Select Machine.ReadWrite.All under Machine and Select Add Permission to add the respective permission to the app



Once it's been completed you can see the permission added to the application, but you can see Not granted on the right-hand side, tap on Grant admin consent



Tap on Yes, to Grant admin consent



once it's granted you can see the yellow exclamatory mark is changed to the green tick



Now the app is created you can see the app under App Registration



Open the App and copy Application (Client) ID and Directory (tenant) ID these values need to be replaced in PowerShell script



Create a Client Secret key, for that navigate to Certificate & Secrets in the respective app click on Client Secrets and tap New Client Secret



Provide a name for the secret key and the validity of the key I had selected by default 6months but you can change accordingly and click on ADD to create a secret key



Once the key is generated copy the value and keep it handy and safe



Copy the below Powershell script to ADD tag in MDE 

##############################################
# The Script will Add tags to MDE using API  #
##############################################
#Paste your tenant ID,app ID,app keys
#This will create and Store auth token for future use
$tenantId = ‘’ #Paste Your Tenant ID
$appId = ‘’    #paste Your App ID
$appSecret = ‘’  #paste your App Key
$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$tenantId/oauth2/token"
$authBody = [Ordered] @{
   resource = “$resourceAppIdUri”
    client_id = “$appId”
    client_secret = “$appSecret”
    grant_type = ‘client_credentials’
}
#Authorize ad connect 
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
$headers = @{
        ‘Content-Type’ = ‘application/json’
        Accept = ‘application/json’
        Authorization = “Bearer $token”
    }
# Clean variables
$Data = @();
$MachineName = $null;
$MachineTag = $null;
$MachineId = $null;
$Data = Import-Csv -Path C:\Users\anandp\Desktop\test_tag.csv # replace with your file path 
# Add Tag as per the input file  
$Data | foreach {
    $MachineName = $($_.Name);
    $MachineTag = $($_.Tag);
    $url = “https://api.securitycenter.microsoft.com/api/machines/$MachineName" 
    $webResponse = Invoke-RestMethod -Method Get -Uri $url -Headers $headers -ErrorAction Stop
    $MachineId = $webResponse.id;
    $body = @{
      “Value”=$MachineTag;
      “Action”=”Add”;
    }
    $url = “https://api.securitycenter.microsoft.com/api/machines/$MachineId/tags” 
    $webResponse = Invoke-WebRequest -Method Post -Uri $url -Headers $headers -Body ($body|ConvertTo-Json) -ContentType “application/json” -ErrorAction Stop
    # Clean variables 
    $MachineName = $null;
    $MachineTag = $null;
    $MachineId = $null;
}

Copy the below Powershell script to Remove the tag in MDE 

##############################################
# The Script will Remove tags in MDE using API  #
##############################################
#Paste your tenant ID,app ID,app keys
#This will create and Store auth token for future use
$tenantId = ‘’ #Paste Your Tenant ID
$appId = ‘’    #paste Your App ID
$appSecret = ‘’  #paste your App Key
$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$tenantId/oauth2/token"
$authBody = [Ordered] @{
   resource = “$resourceAppIdUri”
    client_id = “$appId”
    client_secret = “$appSecret”
    grant_type = ‘client_credentials’
}
#Authorize ad connect 
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
$headers = @{
        ‘Content-Type’ = ‘application/json’
        Accept = ‘application/json’
        Authorization = “Bearer $token”
    }
# Clean variables
$Data = @();
$MachineName = $null;
$MachineTag = $null;
$MachineId = $null;
$Data = Import-Csv -Path C:\Users\anandp\Desktop\test_tag.csv # replace with your file path 
# Add Tag as per the input file  
$Data | foreach {
    $MachineName = $($_.Name);
    $MachineTag = $($_.Tag);
    $url = “https://api.securitycenter.microsoft.com/api/machines/$MachineName" 
    $webResponse = Invoke-RestMethod -Method Get -Uri $url -Headers $headers -ErrorAction Stop
    $MachineId = $webResponse.id;
    $body = @{
      “Value”=$MachineTag;
      “Action”=”Remove”;
    }
    $url = “https://api.securitycenter.microsoft.com/api/machines/$MachineId/tags” 
    $webResponse = Invoke-WebRequest -Method Post -Uri $url -Headers $headers -Body ($body|ConvertTo-Json) -ContentType “application/json” -ErrorAction Stop
    # Clean variables 
    $MachineName = $null;
    $MachineTag = $null;
    $MachineId = $null;
}

Create a CSV file and add the devices and tag name, if it's domain-joined make sure you are providing FQDN of the device if you need to check the FQDn of the device either you can check-in machine or you can use API as I explained in my Previous Blog Link








Run the PowerShell to Add the tags and to Remove the tags as well, as a result of adding the tags you can see the devices have MiamiDC tag added


Reference








1,540 views0 comments

Recent Posts

See All
bottom of page