Azure Active Directory cmdlets for configuring group settings

• 11/08/2019
• 7 minutes to read
• • 
  • 
  • 
  • 
  • 
  • +4

This article contains instructions for using Azure Active Directory (Azure AD) PowerShell cmdlets to create and update groups. This content applies only to Office 365 groups (sometimes called unified groups).

For more information on how to prevent non-administrator users from creating security groups, set Set-MsolCompanySettings -UsersPermissionToCreateGroupsEnabled $False as described in Set-MSOLCompanySettings.

Office 365 Groups settings are configured using a Settings object and a SettingsTemplate object. Initially, you don't see any Settings objects in your directory, because your directory is configured with the default settings. To change the default settings, you must create a new settings object using a settings template. Settings templates are defined by Microsoft. There are several different settings templates. To configure Office 365 group settings for your directory, you use the template named "Group.Unified". To configure Office 365 group settings on a single group, use the template named "Group.Unified.Guest". This template is used to manage guest access to an Office 365 group.

The cmdlets are part of the Azure Active Directory PowerShell V2 module. For instructions how to download and install the module on your computer, see the article Azure Active Directory PowerShell Version 2. You can install the version 2 release of the module from the PowerShell gallery.

Install PowerShell cmdlets

Be sure to uninstall any older version of the Azure Active Directory PowerShell for Graph Module for Windows PowerShell and install Azure Active Directory PowerShell for Graph - Public Preview Release 2.0.0.137 before you run the PowerShell commands.

1. Open the Windows PowerShell app as an administrator.

2. Uninstall any previous version of AzureADPreview.

   Uninstall-Module AzureADPreview
   Uninstall-Module azuread
   

3. Install the latest version of AzureADPreview.

   Install-Module AzureADPreview
   

Create settings at the directory level

These steps create settings at directory level, which apply to all Office 365 groups in the directory. The Get-AzureADDirectorySettingTemplate cmdlet is available only in the Azure AD PowerShell Preview module for Graph.

1. In the DirectorySettings cmdlets, you must specify the ID of the SettingsTemplate you want to use. If you do not know this ID, this cmdlet returns the list of all settings templates:

   Get-AzureADDirectorySettingTemplate
   
   

   This cmdlet call returns all templates that are available:

   Id                                   DisplayName         Description
   --                                   -----------         -----------
   62375ab9-6b52-47ed-826b-58e47e0e304b Group.Unified       ...
   08d542b9-071f-4e16-94b0-74abb372e3d9 Group.Unified.Guest Settings for a specific Office 365 group
   16933506-8a8d-4f0d-ad58-e1db05a5b929 Company.BuiltIn     Setting templates define the different settings that can be used for the associ...
   4bc7f740-180e-4586-adb6-38b2e9024e6b Application...
   898f1161-d651-43d1-805c-3b0b388a9fc2 Custom Policy       Settings ...
   5cf42378-d67d-4f36-ba46-e8b86229381d Password Rule       Settings ...
   

2. To add a usage guideline URL, first you need to get the SettingsTemplate object that defines the usage guideline URL value; that is, the Group.Unified template:

   $Template = Get-AzureADDirectorySettingTemplate -Id 62375ab9-6b52-47ed-826b-58e47e0e304b
   

3. Next, create a new settings object based on that template:

   $Setting = $template.CreateDirectorySetting()
   

4. Then update the usage guideline value:

   $Setting["UsageGuidelinesUrl"] = "https://guideline.example.com"
   

5. Then apply the setting:

   Set-AzureADDirectorySetting -Id (Get-AzureADDirectorySetting | where -Property DisplayName -Value "Group.Unified" -EQ).id -DirectorySetting $Setting
   

6. You can read the values using:

   $Setting.Values
   

Update settings at the directory level

To update the value for UsageGuideLinesUrl in the setting template, simply edit the URL with Step 4 above, then perform Step 5 to set the new value.

To remove the value of UsageGuideLinesUrl, edit the URL to be an empty string using Step 4 above:

$Setting["UsageGuidelinesUrl"] = ""

Then perform Step 5 to set the new value.

Template settings

Here are the settings defined in the Group.Unified SettingsTemplate. Unless otherwise indicated, these features require an Azure Active Directory Premium P1 license.

Example: Configure Guest policy for groups at the directory level

1. Get all the setting templates:

   Get-AzureADDirectorySettingTemplate
   

2. To set guest policy for groups at the directory level, you need Group.Unified template

   $Template = Get-AzureADDirectorySettingTemplate -Id 62375ab9-6b52-47ed-826b-58e47e0e304b
   

3. Next, create a new settings object based on that template:

   $Setting = $template.CreateDirectorySetting()
   

4. Then update AllowAddGuests setting

   $Setting["AllowAddGuests"] = $False
   

5. Then apply the setting:

   Set-AzureADDirectorySetting -Id (Get-AzureADDirectorySetting | where -Property DisplayName -Value "Group.Unified" -EQ).id -DirectorySetting $Setting
   

6. You can read the values using:

   $Setting.Values
   

Read settings at the directory level

If you know the name of the setting you want to retrieve, you can use the below cmdlet to retrieve the current settings value. In this example, we're retrieving the value for a setting named "UsageGuidelinesUrl."

(Get-AzureADDirectorySetting).Values | Where-Object -Property Name -Value UsageGuidelinesUrl -EQ

These steps read settings at directory level, which apply to all Office groups in the directory.

1. Read all existing directory settings:

   Get-AzureADDirectorySetting -All $True
   

   This cmdlet returns a list of all directory settings:

   Id                                   DisplayName   TemplateId                           Values
   --                                   -----------   ----------                           ------
   c391b57d-5783-4c53-9236-cefb5c6ef323 Group.Unified 62375ab9-6b52-47ed-826b-58e47e0e304b {class SettingValue {...
   

2. Read all settings for a specific group:

   Get-AzureADObjectSetting -TargetObjectId ab6a3887-776a-4db7-9da4-ea2b0d63c504 -TargetType Groups
   

3. Read all directory settings values of a specific directory settings object, using Settings ID GUID:

   (Get-AzureADDirectorySetting -Id c391b57d-5783-4c53-9236-cefb5c6ef323).values
   

   This cmdlet returns the names and values in this settings object for this specific group:

   Name                          Value
   ----                          -----
   ClassificationDescriptions
   DefaultClassification
   PrefixSuffixNamingRequirement
   CustomBlockedWordsList        
   AllowGuestsToBeGroupOwner     False 
   AllowGuestsToAccessGroups     True
   GuestUsageGuidelinesUrl
   GroupCreationAllowedGroupId
   AllowAddGuests              True
   UsageGuidelinesUrl            https://guideline.example.com
   ClassificationList
   EnableGroupCreation           True
   

Remove settings at the directory level

This step removes settings at directory level, which apply to all Office groups in the directory.

Remove-AzureADDirectorySetting –Id c391b57d-5783-4c53-9236-cefb5c6ef323c

Create settings for a specific group

1. Search for the settings template named "Groups.Unified.Guest"

   Get-AzureADDirectorySettingTemplate
   
   Id                                   DisplayName            Description
   --                                   -----------            -----------
   62375ab9-6b52-47ed-826b-58e47e0e304b Group.Unified          ...
   08d542b9-071f-4e16-94b0-74abb372e3d9 Group.Unified.Guest    Settings for a specific Office 365 group
   4bc7f740-180e-4586-adb6-38b2e9024e6b Application            ...
   898f1161-d651-43d1-805c-3b0b388a9fc2 Custom Policy Settings ...
   5cf42378-d67d-4f36-ba46-e8b86229381d Password Rule Settings ...
   

2. Retrieve the template object for the Groups.Unified.Guest template:

   $Template1 = Get-AzureADDirectorySettingTemplate -Id 08d542b9-071f-4e16-94b0-74abb372e3d9
   

3. Create a new settings object from the template:

   $SettingCopy = $Template1.CreateDirectorySetting()
   

4. Set the setting to the required value:

   $SettingCopy["AllowAddGuests"]=$False
   

5. Get the ID of the group you want to apply this setting to:

   $groupID= (Get-AzureADGroup -SearchString "YourGroupName").ObjectId
   

6. Create the new setting for the required group in the directory:

   New-AzureADObjectSetting -TargetType Groups -TargetObjectId $groupID -DirectorySetting $SettingCopy
   

7. To verify the settings, run this command:

   Get-AzureADObjectSetting -TargetObjectId $groupID -TargetType Groups | fl Values
   

Update settings for a specific group

1. Get the ID of the group whose setting you want to update:

   $groupID= (Get-AzureADGroup -SearchString "YourGroupName").ObjectId
   

2. Retrieve the setting of the group:

   $Setting = Get-AzureADObjectSetting -TargetObjectId $groupID -TargetType Groups
   

3. Update the setting of the group as you need, e.g.

   $Setting["AllowAddGuests"] = $True
   

4. Then get the ID of the setting for this specific group:

   Get-AzureADObjectSetting -TargetObjectId $groupID -TargetType Groups
   

   You will get a response similar to this:

   Id                                   DisplayName            TemplateId                             Values
   --                                   -----------            -----------                            ----------
   2dbee4ca-c3b6-4f0d-9610-d15569639e1a Group.Unified.Guest    08d542b9-071f-4e16-94b0-74abb372e3d9   {class SettingValue {...
   

5. Then you can set the new value for this setting:

   Set-AzureADObjectSetting -TargetType Groups -TargetObjectId $groupID -Id 2dbee4ca-c3b6-4f0d-9610-d15569639e1a -DirectorySetting $Setting
   

6. You can read the value of the setting to make sure it has been updated correctly:

   Get-AzureADObjectSetting -TargetObjectId $groupID -TargetType Groups | fl Values
   

Cmdlet syntax reference

You can find more Azure Active Directory PowerShell documentation at Azure Active Directory Cmdlets.

Additional reading

• Managing access to resources with Azure Active Directory groups
• Integrating your on-premises identities with Azure Active Directory