Introduction
A couple of weeks ago we reviewed how to go through the Graph cmdlets and also exposed all of the submodules that are present in the Graph PowerShell module – read about that here. Now we are going to explore each of these submodules and break down as much as possible the cmdlets from each module. One module, the Microsoft.Graph.Authentication module, has already been broken down in this article. Looking over the list of available options we have quite a few options to choose from. For this post we will review another small module ‘Microsoft.Graph.DirectoryObjects’ to see what cmdlets are available and what can be done with them.
Available Cmdlets
First, we need to list all cmdlets in the module:
Get-Command | Where Source -eq Microsoft.Graph.DirectoryObjects
Which reveals these (11) cmdlets:
Confirm-MgDirectoryObjectMemberGroup Confirm-MgDirectoryObjectMemberObject Get-MgDirectoryObject Get-MgDirectoryObjectAvailableExtensionProperty Get-MgDirectoryObjectById Get-MgDirectoryObjectMemberGroup Get-MgDirectoryObjectMemberObject Get-MgDirectoryObjectUserOwnedObject [appears in the list and then is removed …] New-MgDirectoryObject Remove-MgDirectoryObject Test-MgDirectoryObjectProperty Update-MgDirectoryObject
Cmdlet Examination
Confirm-MgDirectoryObjectMemberGroup
This cmdlet is used to check membership of a user, group, etc., in a set of groups (up to 20 at a time) and it returns which groups that object is a member of. In order to use this cmdlet we need to get a list of IDs for groups we wish to check as well as the ID of the object we wish to check as well. How can we do that? Well, we need two cmdlets, Get-MgGroup which will list groups in a tenant, and depending on the object, a cmdlet like Get-MgUser would pull users in a tenant.
Sample Get-MgUser with identifying information:
Next, Get-MgGroup with identifying information as well:
There is an example for this cmdlet, but we do not have to follow the exact setup and an simply run it like so (not the group IDs are in a comma separated list:
Confirm-MgDirectoryObjectMemberGroup -DirectoryObjectId 77893d3e-0064-40fd-ad52-fa86e3c2226d -GroupIds 034ff765-2e87-483d-85c3-4a2b32b469e5,1c35706a-15ba-4ab1-b700-73af7c43a4ed
The cmdlet will return the groups that the directory object is a member of:
Which is good if you remember the Group’s Id … but if you do not:
$Confirmed = Confirm-MgDirectoryObjectMemberGroup -DirectoryObjectId 77893d3e-0064-40fd-ad52-fa86e3c2226d -GroupIds 034ff765-2e87-483d-85c3-4a2b32b469e5,1c35706a-15ba-4ab1-b700-73af7c43a4ed $Confirmed | Foreach {Get-MgGroup -GroupID $_}
Which then gives us a more human readable form of output:
That’s it, pretty easy to use.
Confirm-MgDirectoryObjectMemberObject
With this cmdlet, we have a similar comparison to the previous cmdlet where we are looking for object membership in a group. If we use the same Directory Object ID and Group IDs we get this:
Confirm-MgDirectoryObjectMemberObject -DirectoryObjectId 77893d3e-0064-40fd-ad52-fa86e3c2226d -Ids 1c35706a-15ba-4ab1-b700-73af7c43a4ed,034ff765-2e87-483d-85c3-4a2b32b469e5
Using a similar set of code to the last one, to identify groups:
$Confirmed = Confirm-MgDirectoryObjectMemberObject -DirectoryObjectId 77893d3e-0064-40fd-ad52-fa86e3c2226d -Ids 034ff765-2e87-483d-85c3-4a2b32b469e5,1c35706a-15ba-4ab1-b700-73af7c43a4ed $Confirmed | Foreach {Get-MgGroup -GroupID $_}
Only difference is the cmdlet name and instead of ‘GroupIds’, we use ‘Ids’.
Get-MgDirectoryObject
With this cmdlet we can pull details about objects in a tenant’s Directory. For example, we jus
Get-MgDirectoryObject -DirectoryObjectId 77893d3e-0064-40fd-ad52-fa86e3c2226d
Not great output from this one:
However, if we add ‘| Fl’ we get a bit more information on this object, but still not great:
How can we extract better information on this object? Well, we see in the above screenshot that the object has a property called ‘AdditionalProperties’ which seems to have some data in in, let’s extract that:
(Get-MgDirectoryObject -DirectoryObjectId 77893d3e-0064-40fd-ad52-fa86e3c2226d).AdditionalProperties
Get-MgDirectoryObjectAvailableExtensionProperty
Depending on your configuration, if you’ve added ‘directory extension definitions’ in Azure AD, you can list them with this cmdlet. To learn more about this topic, see this article from Microsoft’s Learn documentation. More than likely, you have not done this and when this cmdlet is run, no results are returned:
Get-MgDirectoryObjectById
This cmdlet will reveal group memeberships for an object in the directory:
(Get-MgDirectoryObjectById -Ids 77893d3e-0064-40fd-ad52-fa86e3c2226d).AdditionalProperties
This displays the same output as Get-MgDirectoryObject, minus one line:
Get-MgDirectoryObjectMemberGroup
With this cmdlet we can get a full list of Group memberships for an object as long as we have the DirectoryObjectId. When using this cmdlet, one required parameter, SecurityEnabledOnly, needs to be used along with the DirectoryObjectId parameter.
Get-MgDirectoryObjectMemberGroup -DirectoryObjectId 77893d3e-0064-40fd-ad52-fa86e3c2226d
If not, we get this error:
Now, if we specify the ‘SecurityEnabledOnly’ parameter, with no value, we only get Security Enabled Groups:
Otherwise, if we use the parameter and supply a Boolean value for it – $True or $False – then we can generate different results. $False will provide all groups:
Get-MgDirectoryObjectMemberObject
Similar to the previous cmdlet which reveals Group Membership, this cmdlet can also reveal Assigned Roles like the Global Administrator. For example (using the previous cmdlet as a guide)
Get-MgDirectoryObjectMemberObject -DirectoryObjectId 77893d3e-0064-40fd-ad52-fa86e3c2226d -SecurityEnabledOnly:$True
Get-MgDirectoryObjectMemberObject -DirectoryObjectId 77893d3e-0064-40fd-ad52-fa86e3c2226d -SecurityEnabledOnly:$False
We can pull information about each group like this: (Security Only for this example):
$Groups = Get-MgDirectoryObjectMemberObject -DirectoryObjectId 77893d3e-0064-40fd-ad52-fa86e3c2226d -SecurityEnabledOnly $Groups | Foreach {$Groups = (Get-MgDirectoryObject -DirectoryObjectId $_).AdditionalProperties ; Foreach ($Group in $Groups) { $Group | ft} }
The first listed group is a Built-In role, while the second one was created by a tenant administrator.
New-MgDirectoryObject
Assume we can create objects. Currently still researching this cmdlet.
Remove-MgDirectoryObject
Removes an object from the directory, assuming the user executing the cmdlet has the correct permissions (Graph permissions):
Remove-MgDirectoryObject -DirectoryObjectId 55d469f1-4438-4114-a570-70d7b57d1ea8
That object has now been removed from the directory. Be careful with this cmdlet as there is no feedback or typical ‘Are you sure?’ message displayed.
Test-MgDirectoryObjectProperty
This cmdlet is used to check that a Microsoft 365 group’s Display Name or Mail Nickname complies with naming policies for groups and is used prior to creating a group in the directory.
Test-MgDirectoryObjectProperty -EntityType Group -DisplayName 'Teds Group'
If there is an issue with the DisplayName or MailNickName, an error will be displayed.
Update-MgDirectoryObject
Use this cmdlet to update some properties in the directory. In this example we are renaming a group that was used for testing, but is now used for production. The new name of the group is ‘Prod-iOS-Group’ for iOS phone users.
$params = @{ DisplayName ="Prod-iOS-Group" } Update-MgDirectoryObject -DirectoryObjectId 16e95489-2194-41a5-8b43-59a679f07f01 -BodyParameter $Params
Executing those two lines updates the display name of the group.
Conclusion
The breakdown of the Microsoft.Graph.DirectoryObjects submodule cmdlets is only the beginning of this deep dive into the Graph module. Next week we will dig into another Graph submodule to see what we can discovery about those cmdlets. Until next time.
————————————————————————————————–
See previous Microsoft Graphposts [ HERE ]
———————————————————————————————————–
Comments? Questions?
Feel free to leave your Comments below! Learn to more efficiently utilize PowerShell to manage Exchange Server, Exchange Online, Microsoft Defender for Office or Microsoft Purview Compliance portals by picking up frequently updated eBooks: