Creating Scope tags in Intune using Graph API (and associating them with the newly created AAD group)

Scope tags short overview

If you’re working with Intune, you’ve certainly encountered the topic of Scope tags – whether by accidentally running into that option or seeing it as an recommendation for scoping the permissions to IT colleagues which are accessing Intune in your environment.

In case you are dealing with big environment which contains hundreds of locations worldwide, it might be a bit hard to plan how are you going to scope the permissions for those who need access to Intune as well (for example, just to have the option of wiping the device or checking whether the Configuration profile applied correctly).

This is where scope tags come into the game and present themselves as a viable option for tagging the Intune objects and exposing this scope tag to certain Intune role. You can imagine the scope tags as virtual labels which you stick to the devices and objects in Intune – only when you make that scope tag visible to the custom role in Intune, then the users having that role will be able to see objects associated with it.

During the planning on how to tag your devices, you need to know how IT support departments on your locations are managing all devices on particular location – for example, maybe they are just supporting Windows devices and there is a separate team supporting mobile devices only.

There are many variations on how to set this up and depends on your organization. For example, maybe you’ll create an Scope tag for the whole country (for example, all devices from Croatia – HR_Device), separate the tags based on operating system (HR_Windows, HR_IOS, HR_Android) or even separate the tags based on the location and operating system inside of the country (HR_Zagreb_Windows, HR_Dubrovnik_iOS, DE_Berlin_Windows) and so on.

Final goal after all is making sure that IT support which is given the permission to access Intune is only able to see devices / objects which belong to their area of responsibility (whether that being the whole region, country, or just one city).

Creating the Scope tags manually

Creating the Scope tags manually in Intune is pretty straightforward – just choose the name for the scope tag, description and which AAD groups are going to be targeted (actually devices which are members of the group). All device objects which are members of that AAD group and are enrolled to Intune will be tagged with that scope tag which you’ve just created.

That means that if you are starting from the scratch, you need to create multiple objects in your AAD and Intune:

  1. Static or dynamic AAD group/s pulling all the devices from particular location, optionally separate groups based on OS
  2. Scope tag in Intune
  3. Assign the AAD group to the scope tag

Not much, but if you have 50+ different groups and tags, you might wanna automate this – at least to have some fun.

Creating the AAD groups and corresponding Scope tags using Powershell and Graph API

In order to create an AAD group (in our case dynamic one), scope tag, and associate that scope tag with the group, I’ve created couple of different Powershell functions for this purpose.

Script can be found on my GitHub page:

https://github.com/TomislavPeharec/Intune/blob/main/New-AADGroupAndScopeTags.ps1

However, keep on reading in order to understand better how it works and what it’s being done during the process.

First what needs to be done is populating the variables which can be found in region Parameters to define. Most of them are self explanatory but let’s just quickly go through them (with examples):

$OS = “Windows” (or any other OS to which devices belong, for example iOS. Used for AAD dynamic group filtering so its important that it reflects the actual available value in AAD)

$Owner = „tomislav.peharec@company.xyz (designated owner of the AAD group)

$UserName = will be automatically derived from the account which is running the script and used in AAD group and Scope Tag descriptions

$Locations = Get-Content “C:\Users\$Username\Desktop\Locations.txt” (airport city codes / country codes or whatever you want to use in a basic TXT file), for example:

$GroupExport = “C:\Users\$Username\Desktop\AAD_groups_created_$(Get-Date -Format ‘dd_MM_yyyy_HH_mm_ss’).csv” (location for exporting the results of AAD group creation and it’s properties)

$TagExport = “C:\Users\$Username\Desktop\Scope_tags_assignment_$(Get-Date -Format ‘dd_MM_yyyy_HH_mm_ss’).csv” (location for exporting the results of scope tag creation and it’s properties)

Requirements for the script to run successfully

In order to create AAD group/s and Scope tag/s successfully, you will need to have corresponding roles in your Azure AD and Intune environment. For Azure AD, User Administrator or equivalent should be sufficient and as for Intune, you’re gonna need Intune Administrator role (I haven’t found the scope tags on the list of permissions available for custom roles). Additionally, prior to executing the script, you will need to authenticate with your administrative account using the Connect-AzureAD and Get-AuthToken functions.

New-AADDynamicGroup function

Basically, function New-AADDynamicGroup is going to create an AAD group according to our defined parameters and store our variable $NewGroup for later using the $Script:NewGroup option which exposes this variable to be available in the scope of the whole script and therefore can be used in other functions later in the script (you can read more about scoping here https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_scopes?view=powershell-7.1).

After creating the group, there is a sleep time of 20 seconds before we assign the owner of the group (I’ve noticed that usually it takes some time for the newly created AAD group to become visible to Add-AzureADGroupOwner cmdlet which is used during the process). In case the account doesn’t exist in the tenant, process will inform you and continue further.

Of course, you need to use Connect-AzureAD cmdlet before and authenticate with account that has enough permissions for the group creation.

New-ScopeTag function

For using the New-ScopeTag function, you will need to authenticate to Graph API for your tenant. Authentication token can be obtained using the well known Get-AuthToken function which will store the token in variable $authToken. Function will use the same values which you’ve defined for creating your group/s ($OS and $Locations) and create the Scope tag object in your Intune environment whose name will be separated by underscore character, for example “ZAG_Windows”.

Here we are also passing further the variable $Script:NewScopeTag for the later use in the script.

Additionally, Description value will be populated according to predefined value which can be manipulated in the variable $DescriptionScopeTag. Current value is picking up the $OS, $Location and $UserName values and enters in the date of the scope tag creation. With $UserName value in the description, we are creating a track of who created the object (can be useful if you have multiple persons working in the environment). For example, result should look something like this:

All ZAG Windows devices (created by tomislav.peharec \ 04.03.2021)

Update-ScopeTag function

Function Update-ScopeTag will use the properties of the scope tag and AAD group objects which were created during the process and it will use them to add that AAD group into the Assignments property of the Scope tag. That basically means that all objects which are part of the group and are enrolled in Intune, will be tagged with this scope tag.

Get-ScopeTag function

Last function Get-ScopeTag will get the respective scope tag object which was just created and pass it’s properties in the custom Powershell object $ScopeTagProperties which is later used in exporting the details to CSV file.

Main script

Main script which is handling all of this with foreach loop also contains few variables which might need to be clarified:

$Description = “Group contains all ” + $Location + ” $OS devices (created by $UserName \ $(Get-Date -Format ‘dd.MM.yyyy’))” (description which will be assigned to AAD group)

$Rule = ‘(device.deviceOSType -eq ‘ + ‘”‘ + $OS + ‘”‘ + “)” + ‘ and (device.displayName -startsWith ‘ + ‘”‘ + $Location + ‘”‘ + “)” (rule for the dynamic group, combined based on $Location and $OS variables)

$GroupName = “SG_D_” + $Location + “_$OS” (naming which will be used for the AAD group, SG would be in this case Security group, D would stand for dynamic type, rest combined from respective location value and OS in the loop)

Creation and assignment process

When you run the script, steps which were successfully taken or failed will be shown in the console. For example, this is an successful console output for 3 different locations:

When the script is finished, you can check your AAD and you should see the groups which you’ve just created, as for example:

When you open any of the groups, you’ll see that they should have owner assigned as well as the dynamic rule which was defined in foreach loop.

If you jump to Intune and head over to the Scope tags blade (https://endpoint.microsoft.com/#blade/Microsoft_Intune_DeviceSettings/RolesLandingMenuBlade/scopeTags), you should see the corresponding three Scope tags created according to the naming convention:

When you select one of them, you should see that it’s assigned to its corresponding AAD group which was just created:

All of this can also be confirmed by going to the place where you’ve decided to store your CSV files which should appear in a following manner:

When you open the files and arrange the columns, you should see the output generated by the script:

AAD groups details:

Scope tags details:

I would also imagine that some of you will want to go through this same process, but for already existing AAD groups. In the future, I’m planning to create a function which will read the AAD groups which you specified, and will just continue with creating the Scope tags and their assignment.

This wraps up this post, in case you have some suggestions what could be changed or you have more efficient way of doing this, feel free to write a comment below.

One thought on “Creating Scope tags in Intune using Graph API (and associating them with the newly created AAD group)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: