If you ever need to win an argument as to the state of the Graph API and the corresponding SDK for PowerShell, you can just refer to the directorySettings resource, a prime example of Microsoft’s tendency to release a feature and never look back. Not only are said directory settings and the “parent” directory setting templates still only available in the /beta branch, almost a decade after the initial release, but their relationship to the group settings resource was never properly addressed either. Let us also not forget the schema itself, with directory settings objects exposed under the “top level” /beta/settings endpoint!
Combine all that with the fact that no GUI exists for working with most of the directory settings/templates, and it is really no wonder that this remains one of the most convoluted parts of the service. While there are plenty of articles available that will guide you over the process of configuring directory settings, such as those related to Microsoft 365 Groups, even the official documentation still lists the beta cmdlets in all of the examples provided. Which begs the question, how can you manage the Microsoft 365 Group settings via an officially supported tool, such as the GA release of the Graph SDK for PowerShell?
How directory settings work
Before answering that question, it’s worth reminding the reader how exactly the directory settings concept works. In simple words, Microsoft pushes a set of default configurations via directorySettingTemplate objects, a number of which exists in every tenant. These templates are responsible for enforcing a wide variety of controls, ranging from settings for Microsoft 365 Groups, to naming policies, to password protection to consent policies. If a tenant wants to make a change to the default configuration, an admin will need to instantiate a directorySettings object based on a given template, and update one or more of the controls exposed therein.
While most of the settings are configured on the tenant level, some expose an object-specific configuration instead. This is the case for Microsoft 365 Group’s Guest settings, controlled via the Group.Unified.Guest template (with if of 08d542b9-071f-4e16-94b0-74abb372e3d9). For such, you create a directory setting object based on the template, then assign it to a set of groups, on a per-object basis. We will examine examples on how to do that in the following section.
As mentioned above, the directorySettingTemplate and directorySettings resources are currently only exposed via the /beta Graph API endpoints. For a “supported” /v1.0 implementation, we can turn to their sibling groupSettingTemplates and groupSettings resources instead, which basically represent a subset of the aforementioned resources. For the purposes of this article, the only two settings template we care about are the Group.Unified one, with id of 62375ab9-6b52-47ed-826b-58e47e0e304b, and the Group.Unified.Guest one, with id of 08d542b9-071f-4e16-94b0-74abb372e3d9.
Before we move on to specific examples, we need to also cover the permissions needed. As we will be working with directory level settings, unsurprisingly they are highly privileged: Directory.Read.All is needed to read the properties of templates and settings objects and Directory.ReadWrite.All to make changes. If you are going to be executing any of the below examples in the context of a user, you will need at least the Global Reader role assigned for read operations and the Groups administrator one for updating any group-related settings. Refer to the official documentation for more details.
Scenario #1: Control Microsoft 365 Group settings on the tenant level
The bulk of Microsoft 365 Group settings are exposed via the Group.Unified template. For a supported method to manage said template, we can use the Graph SDK’s absurdly named Get-MgGroupSettingTemplateGroupSettingTemplate cmdlet:
#Fetch all (group) setting templates Get-MgGroupSettingTemplateGroupSettingTemplate #Fetch just the Group.Unified template Get-MgGroupSettingTemplateGroupSettingTemplate -GroupSettingTemplateId 62375ab9-6b52-47ed-826b-58e47e0e304b
We can use the following to review the set of Microsoft 365 Group settings exposed via the template:
Get-MgGroupSettingTemplateGroupSettingTemplate -GroupSettingTemplateId 62375ab9-6b52-47ed-826b-58e47e0e304b | select -ExpandProperty Values | select Name, DefaultValue, Description
As we can see from the above screenshot, the default settings allow every user in the tenant to create Microsoft 365 Groups, and every Group will allow Guests to be added. Should you want to modify any of the default settings, you need to instantiate a copy of the Group.Unified settings template and make any desired changes therein. An important thing to note here is that only one such settings object can exist in the tenant, so it is best to first check whether it was previously created. We can do that via the Get-MgGroupSetting cmdlet:
#Fetch all (group) setting objects
Get-MgGroupSetting
#Check if a settings object using the template exists
$res = Get-MgGroupSetting | ? {$_.TemplateId -eq "62375ab9-6b52-47ed-826b-58e47e0e304b"}
As the Get-MgGroupSetting cmdlet does not support server-side filtering, you must do the filtering client-side. Either the id of the template or its display name can be used, the former being the safer option. In the example above, the $res variable is used to store the output, which you can then examine in order to confirm the existence of a Group.Unified settings object and review its current configuration. For example, in my tenant such object exists and has the following values:
$res.Values Name Value ---- ----- NewUnifiedGroupWritebackDefault true EnableMIPLabels True CustomBlockedWordsList EnableMSStandardBlockedWords False ClassificationDescriptions DefaultClassification PrefixSuffixNamingRequirement GRP-[GroupName] AllowGuestsToBeGroupOwner False AllowGuestsToAccessGroups True GuestUsageGuidelinesUrl GroupCreationAllowedGroupId AllowToAddGuests True UsageGuidelinesUrl ClassificationList EnableGroupCreation true
To modify any of the settings above, you can use the following syntax:
$params = @{
Values = @(
@{
Name = "AllowToAddGuests"
Value = "false"
}
@{
Name = "EnableGroupCreation"
Value = "false"
}
)
}
Update-MgGroupSetting -GroupSettingId $res.id -BodyParameter $params
You do not need to provide values for any of the settings that you don’t want to modify, existing values will be preserved. If you prefer, you can also pass the entire collection of settings, as stored within the $res.values property. Due to the oddities of the Graph SDK for PowerShell however, updating those is not as easy as it should be. Here’s an example just in case:
#Get the setting object
$res = Get-MgGroupSetting | ? {$_.TemplateId -eq "62375ab9-6b52-47ed-826b-58e47e0e304b"}
#Set the desired values
foreach ($r in $res.Values) { if ($r.Name -in @("AllowToAddGuests","EnableGroupCreation")) { $r.Value = "false" }}
#Commit the changes
Update-MgGroupSetting -GroupSettingId $res.id -BodyParameter $res
The example above is only appropriate for our specific scenario where we want to toggle off few settings with boolean values. For the generic scenario, you’d have to go over each of the values and update it individually. While in previous iterations the returned object was a hash-table, and thus much easier to update, nowadays you have to code around the SDK’s oddities. Oh and did I mention that the setting names are case-sensitive?
We need to also cover the scenario where a settings object doesn’t already exist. In this case, you have to instantiate it first by copying the template configuration. To do that, we pass the corresponding templateId value to the New-MgGroupSetting cmdlet. Doing so will provision a new settings object, inheriting the default setting values from the template. As the idea here is to change some of the defaults, you can either update the settings object after it was provisioned (what we did in the above examples), or you can directly pass values to the settings you want modified. Here’s an example:
$params = @{
templateId = "62375ab9-6b52-47ed-826b-58e47e0e304b"
Values = @(
@{
Name = "AllowToAddGuests"
Value = "false"
}
@{
Name = "EnableGroupCreation"
Value = "false"
}
)
}
New-MgGroupSetting -BodyParameter $params -Verbose -Debug
Remember that if a setting object already exists, the above cmdlet will fail, and you have to use the Update-MgGroupSetting method instead. This is also the method you should use if you want to modify existing setting values. Lastly, if at some point you want to return to the default configuration, you can remove the corresponding setting object, by running the Remove-MgGroupSetting cmdlet and passing the id of the corresponding setting object (not the same thing as the templateId!).
#Get the setting object corresponding to a given template
$res = Get-MgGroupSetting | ? {$_.TemplateId -eq "62375ab9-6b52-47ed-826b-58e47e0e304b"}
#Remove the setting object
Remove-MgGroupSetting -GroupSettingId $res.Id
#Do it all in one go
Remove-MgGroupSetting -GroupSettingId (Get-MgGroupSetting | ? {$_.TemplateId -eq "62375ab9-6b52-47ed-826b-58e47e0e304b"}).Id
Scenario #2:Control Microsoft 365 Group settings on a per-group basis
Thus far, we’ve only explored configuring the tenant-wide Microsoft 365 Group settings, as exposed via the Group.Unified template (with id of 62375ab9-6b52-47ed-826b-58e47e0e304b). Another group-related settings template exists, namely the Group.Unified.Guest one (with id of 08d542b9-071f-4e16-94b0-74abb372e3d9), which can be used to control settings on a per-group basis. Or should I say setting, as only a single one is actually exposed:
$resT = Get-MgGroupSettingTemplateGroupSettingTemplate -GroupSettingTemplateId "08d542b9-071f-4e16-94b0-74abb372e3d9" $resT.Values DefaultValue Description Name Type ------------ ----------- ---- ---- true Flag indicating if guests are allowed in a specific Unified Group. AllowToAddGuests System.Boolean
As you can see from the above output, the Group.Unified.Guest template allows you to control guest invitation to a group and the default value is to allow access. Should you want to block guest access to specific groups, you must instantiate a new setting object and set the value to false, then assign said settings object to the group(s) in question.
As with the previous scenario, you need to account for scenarios where a setting object already exists. The difference is that this time around, the setting object is configured on the group level, not the directory level. The Get-MgGroupSetting cmdlet can still be used to get us the required info, but this time around, we need to run it with the –GroupId parameter. Even if you have multiple Microsoft 365 Groups configured with their own settings object, the output of Get-MgGroupSetting without any parameters will not reveal those. Instead, you run the check on the group level. Here’s an example:
#Set the Microsoft 365 Group ID for reuse
$GID = "12c96e98-45fd-4591-93e5-cca4fd91666b"
#Verify whether a settings object exists
$res = Get-MgGroupSetting -GroupId $GID
#Create a new settings object
$params = @{
templateId = "08d542b9-071f-4e16-94b0-74abb372e3d9"
values = @(
@{
name = "AllowToAddGuests"
value = "False"
}
)
}
New-MgGroupSetting -BodyParameter $params -GroupId $GID
#Verify the settings object exists
Get-MgGroupSetting -GroupId $GID | select -ExpandProperty Values
Name Value
---- -----
AllowToAddGuests False
In scenarios where a settings object already exists for the group in question, you only need to update it:
$params = @{
values = @(
@{
name = "AllowToAddGuests"
value = "False"
}
)
}
Update-MgGroupSetting -GroupSettingId $res.id -BodyParameter $params -GroupId $GID
An important thing to remember is that the org-wide settings always take precedence over the object-specific ones. If you have configured a settings object on the directory level and disabled guest access therein, i.e. the AllowToAddGuests setting is set to “false” on the tenant level, any group-level configuration for the same setting will be ignored. Therefore, if you only need to enable this setting for a subset of your Microsoft 365 Group objects, you must set it to “true” on the tenant level first, then iterate over each Group where you want it disabled and create a group-level settings object. “Open” by default, that is.
If you want to revert the settings for a specific Microsoft 365 group to their defaults, you need to remove the settings object.
$res = Get-MgGroupSetting -GroupId $GID Remove-MgGroupSetting -GroupId $GUD -GroupSettingId $res.id
Summary
In summary, in this article we explored the only “supported” method to configure Microsoft 365 Group settings exposed as part of the Group.Unified and Group.Unified.Guest setting templates. With both the MSOnline and AzureAD modules now deprecated, the Graph SDK for PowerShell remains your only option here, unless you want to deal with raw Graph API requests that is. Microsoft is yet to GA the directorySettting and directorySettingTemplate endpoints and methods, so we are forced to use the “group” settings endpoints as a workaround. Give them 10 more years I suppose.
Before closing the article, let me just mention that there are more settings that you can control via setting templates/objects. It is unfortunate that Microsoft has not exposed most of them via any sort of GUI and we need to deal with convoluted JSON syntax and crappy PowerShell implementations. And, documentation is almost non-existent nowadays, for example none of the Graph API articles have a proper list of settings that are part of the Group.Unified template. While you can find their description in this article, the same cannot be said for most of the other setting templates.