Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update active-directory-accessmanagement-groups-settings-cmdlets.md #1079

Merged
merged 1 commit into from
Mar 17, 2017
Merged

Update active-directory-accessmanagement-groups-settings-cmdlets.md #1079

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 126 additions & 47 deletions ...s/active-directory/active-directory-accessmanagement-groups-settings-cmdlets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,104 +18,183 @@ ms.author: curtand

---
# Azure Active Directory cmdlets for configuring group settings
The following settings for unified groups can be configured in your directory:

1. Classifications: the comma-separated list of classifications that users can set on a group. Examples would be “Classified”, “Secret”, and “Top Secret.”
2. Usage Guidelines URL: a URL that points users to the terms of use for using Unified Groups, as defined by your organization. This URL will show up in the user interface where users use groups.
3. Group creation enabled: whether none, some or all users are allowed to create Unified Groups. When set to on, all users can create groups. When set to off, no users can create groups. When off, you can also specify a security group whose users who are still allowed to create groups.
Note: This content only applies to Unified groups, also know as Office365 Groups.

These settings are configured using a Settings and SettingsTemplate objects. Initially, you will not see any Settings objects in your directory. This means your directory is configured with the default settings. To change the default settings, you will create a new settings object using a settings template. Settings templates are defined by Microsoft.
Office365 Groups settings are configured using a Settings object and a SettingsTemplate object. Initially, you will not see any Settings objects in your directory. This means your directory is configured with the default settings. To change the default settings, you will need to create a new settings object using a settings template. Settings templates are defined by Microsoft. There are several different settings templates. To configure group settings for your directory, you will use the template named "Group.Unified". To configure group settings on a single group you will use the template named "Group.Unified.Guest". This template is used to manage guest access to a group.

You can download the module containing the cmdlets used for these operations from the [Microsoft Connect site](http://connect.microsoft.com/site1164/Downloads/DownloadDetails.aspx?DownloadID=59185).
The cmdlets are part of the Azure Active Directory PowerShell V2 Module. For more information about this module and for instructions how to download and install the module on your computer, please refer to [Azure Active Directory PowerShell Version 2](https://docs.microsoft.com/en-us/powershell/azuread/).

## Create settings at the directory level
These steps create settings at directory level, which apply to all Office groups in the directory.
These steps create settings at directory level, which apply to all Unified groups in the directory.

1. If you do not know which SettingTemplate to use, this cmdlet returns the list of settings templates:
1. In the DirectorySettings cmdlets you will need to 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-MsolAllSettingTemplate`
`PS C:> Get-AzureADDirectorySettingTemplate'

![List of settings templates](./media/active-directory-accessmanagement-groups-settings-cmdlets/list-of-templates.png)
This cmdlet call will return 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 Unified 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-MsolSettingTemplate –TemplateId 62375ab9-6b52-47ed-826b-58e47e0e304b`
`$Template = Get-AzureADDirectorySettingTemplate -Id 62375ab9-6b52-47ed-826b-58e47e0e304b`
3. Next, create a new settings object based on that template:

`$setting = $template.CreateSettingsObject()`
`$Setting = $template.CreateDirectorySetting()`
4. Then update the usage guideline value:

`$setting["UsageGuidelinesUrl"] = "<https://guideline.com>"`
5. Finally, apply the settings:

`New-MsolSettings –SettingsObject $setting`
`New-AzureADDirectorySetting -DirectorySetting $settings'

Upon successful completion, the cmdlet returns the Id of the new settings object:

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

![Add a usage guideline URL](./media/active-directory-accessmanagement-groups-settings-cmdlets/add-usage-guideline-url.png)

Here are the settings defined in the Group.Unified SettingsTemplate.

| **Setting** | **Description** |
| --- | --- |
| <ul><li>ClassificationList<li>Type: String<li>Default: “” |A comma-delimited list of valid classification values that can be applied to Unified Groups. |
| <ul><li>EnableGroupCreation<li>Type: Boolean<li>Default: True |The flag indicating whether Unified Group creation is allowed in the directory. |
| <ul><li>GroupCreationAllowedGroupId<li>Type: String<li>Default: “” |GUID of the security group that is allowed to create Unified Groups even when EnableGroupCreation == false. |
| <ul><li>GroupCreationAllowedGroupId<li>Type: String<li>Default: “” |GUID of the security group for which the members are allowed to create Unified Groups even when EnableGroupCreation == false. |
| <ul><li>UsageGuidelinesUrl<li>Type: String<li>Default: “” |A link to the Group Usage Guidelines. |
| <ul><li>ClassificationDescriptions<li>Type: String<li>Default: “” | A comma-delimited list of classification descriptions. |
| <ul><li>DefaultClassification<li>Type: String<li>Default: “” | The classification that is to be used as the default classification for a group if none was specified.|
| <ul><li>PrefixSuffixNamingRequirement<li>Type: String<li>Default: “” |Not implemented yet
| <ul><li>AllowGuestsToBeGroupOwner<li>Type: Boolean<li>Default: False | Boolean indicating whether or not a guest user can be an owner of groups. |
| <ul><li>AllowGuestsToAccessGroups<li>Type: Boolean<li>Default: True | Boolean indicating whether or not a guest user can have access to Unified groups' content. |
| <ul><li>GuestUsageGuidelinesUrl<li>Type: String<li>Default: “” | The url of a link to the guest usage guidelines. |
| <ul><li>AllowToAddGuests<li>Type: Boolean<li>Default: True | A boolean indicating whether or not is is allowed to add guests to this directory.|
| <ul><li>ClassificationList<li>Type: String<li>Default: “” |A comma-delimited list of valid classification values that can be applied to Unified Groups. |
| <ul><li>EnableGroupCreation<li>Type: Boolean<li>Default: True | A boolean indicating whether or not non-admin users can create new Unified groups. |
'

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

1. Read all existing directory settings:

`Get-MsolAllSettings`
`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-MsolAllSettings -TargetType Groups -TargetObjectId <groupObjectId>`
3. Read specific directory settings, using SettingId GUID:
`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
AllowGuestsToBeGroupOwner False
AllowGuestsToAccessGroups True
GuestUsageGuidelinesUrl
GroupCreationAllowedGroupId
AllowToAddGuests True
UsageGuidelinesUrl <https://guideline.com>
ClassificationList
EnableGroupCreation True`
'

## Update settings for a specific group

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

'Get-AzureADDirectorySettingTemplate

`Get-MsolSettings –SettingId dbbcb0ea-a6ff-4b44-a1f3-9d7cef74984c`
Id DisplayName Description
-- ----------- -----------
62375ab9-6b52-47ed-826b-58e47e0e304b Group.Unified ...
08d542b9-071f-4e16-94b0-74abb372e3d9 Group.Unified.Guest Settings for a specific Unified 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:
'
$Template = Get-AzureADDirectorySettingTemplate -Id 08d542b9-071f-4e16-94b0-74abb372e3d9
'
3. Create a new settings object from the template:

![Settings ID GUID](./media/active-directory-accessmanagement-groups-settings-cmdlets/settings-id-guid.png)
'
$Setting = $Template.CreateDirectorySetting()
'

4. Set the setting to the required value:

'
$Setting["AllowToAddGuests"]=$False
'

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

'
New-AzureADObjectSetting -TargetType Groups -TargetObjectId ab6a3887-776a-4db7-9da4-ea2b0d63c504 -DirectorySetting $Setting


Id DisplayName TemplateId Values
-- ----------- ---------- ------
25651479-a26e-4181-afce-ce24111b2cb5 08d542b9-071f-4e16-94b0-74abb372e3d9 {class SettingValue {...
'

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

1. Get the existing Settings object:
These steps update settings at directory level, which apply to all Unified groups in the directory. These examples assume there is already a Settings object in your directory.

1. Find the existing Settings object:

`$setting = Get-MsolSettings –SettingId dbbcb0ea-a6ff-4b44-a1f3-9d7cef74984c`
2. Get the value you want to update:
'Get-AzureADDirectorySetting | Where-object -Property Displayname -Value "Group.Unified" -EQ

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

`$setting = Get-AzureADDirectorySetting –Id c391b57d-5783-4c53-9236-cefb5c6ef323`

`$value = $Setting.GetSettingsValue()`
3. Update the value:

`$value["AllowToAddGuests"] = "false"`
`$Setting["AllowToAddGuests"] = "false"`

4. Update the setting:

`Set-MsolSettings –SettingId dbbcb0ea-a6ff-4b44-a1f3-9d7cef74984c –SettingsValue $value`
'Set-AzureADDirectorySetting -Id c391b57d-5783-4c53-9236-cefb5c6ef323 -DirectorySetting $Setting'

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

`Remove-MsolSettings –SettingId dbbcb0ea-a6ff-4b44-a1f3-9d7cef74984c`
`Remove-AzureADDirectorySetting –Id c391b57d-5783-4c53-9236-cefb5c6ef323c`

## Cmdlet syntax reference
You can find more Azure Active Directory PowerShell documentation at [Azure Active Directory Cmdlets](http://go.microsoft.com/fwlink/p/?LinkId=808260).

## SettingsTemplate object reference (Group.Unified SettingsTemplate object)
* "name": "EnableGroupCreation", "type": "System.Boolean", "defaultValue": "true", "description": "A boolean flag indicating if the Unified Group creation feature is on."
* "name": "GroupCreationAllowedGroupId", "type": "System.Guid", "defaultValue": "", "description": "GUID of the security group that is whitelisted to create Unified Groups."
* "name": "ClassificationList", "type": "System.String", "defaultValue": "", "description": "A comma-delimited list of valid classification values that can be applied to Unified Groups."
* "name": "UsageGuidelinesUrl", "type": "System.String", "defaultValue": "", "description": "A link to the Group Usage Guidelines."

| name | type | defaultValue | description |
| --- | --- | --- | --- |
| "EnableGroupCreation" |"System.Boolean" |"true" |"A boolean flag indicating if the Unified Group creation feature is on." |
| "GroupCreationAllowedGroupId" |"System.Guid" |"" |"GUID of the security group that is whitelisted to create Unified Groups." |
| "ClassificationList" |"System.String" |"" |"A comma-delimited list of valid classification values that can be applied to Unified Groups." |
| "UsageGuidelinesUrl" |"System.String" |"" |"A link to the Group Usage Guidelines." |

## Next steps
You can find more Azure Active Directory PowerShell documentation at [Azure Active Directory Cmdlets](http://go.microsoft.com/fwlink/p/?LinkId=808260).
You can find more Azure Active Directory PowerShell documentation at [Azure Active Directory Cmdlets](https://docs.microsoft.com/en-us/powershell/azuread/).

Additional instruction from Microsoft program manager Rob de Jong is available at [Rob's Groups Blog](http://robsgroupsblog.com/blog/configuring-settings-for-office-365-groups-in-azure-ad).
## Additional reading

* [Managing access to resources with Azure Active Directory groups](active-directory-manage-groups.md)
* [Integrating your on-premises identities with Azure Active Directory](active-directory-aadconnect.md)