Create Dynamic Microsoft 365 Groups and Teams with PowerShell

No sooner had I published the article about creating dynamic administrative units with PowerShell, the first email arrived asking if the same was possible for dynamic Microsoft 365 groups. The answer is “of course,” but with the caveat that it’s not just a matter of some minor updates to the script.

That being said, the outline for the script to create dynamic groups is broadly the same:

• Find the licensed users in the tenant and extract a list of departments. The departments should be accurate and some care should be taken to eliminate inconsistencies. For instance, some people might be listed as belonging to IT while others belong to the Information Technology department. Decide on one value and apply it to all.
• You might not want to create groups for all departments. The script defines an array of excluded departments that are removed from the set to process.
• Find the set of dynamic Microsoft 365 groups. We need this information to check if a dynamic group already exists for a department.
• For each department, check if a group already exists. If not, define some parameters for the new group, including the membership rule that Entra ID uses to calculate the group members, and run the New-MgGroup cmdlet to create the group.
• Following a successful creation, proceed to team-enable the new group by running the New-MgTeam cmdlet. This is an optional step, but seeing that Teams is the heaviest workload for Microsoft 365 groups, it seemed like a good thing to include.

Let’s examine some of the steps.

Scripting the Creation of a Dynamic Microsoft 365 Group

Here’s an example of creating a new dynamic Microsoft 365 group for the department whose name is stored in the $Dept variable:

Write-Host ("Checking groups for department {0}" -f $Dept)
$Description = ("Dynamic Microsoft 365 group created for the {0} department on {1}" -f $Dept, (Get-Date))
$DisplayName = ("{0} Dynamic group" -f $Dept)
$MailNickName = ("Dynamic.{0}.Group" -f ($Dept -replace " ",""))
$MembershipRule = '(User.Department -eq "' + $Dept +'")'

If ($DisplayName -in $Groups.DisplayName) {
   Write-Host ("Group already exists for {0}" -f $Dept) -ForegroundColor Red
} Else {
# Create the new dynamic Microsoft 365 Group
   $NewGroup = New-MgGroup -DisplayName $DisplayName -Description $Description ` 
   -MailEnabled:$True -SecurityEnabled:$False `
   -MailNickname $MailNickName -GroupTypes "DynamicMembership", "Unified" `
   -MembershipRule $MembershipRule -MembershipRuleProcessingState "On"
}

Wait Before Progressing to Teams

Flushed with the successful creation, you might want to rush to team-enable the new group. However, it’s best to wait 10-15 seconds before proceeding to allow Teams to learn about the new group from Entra ID. If you attempt to team-enable a group immediately after creation, you’ll probably see an error like this:

Failed to execute Templates backend request CreateTeamFromGroupWithTemplateRequest. Request Url: https://teams.microsoft.com/fabric/emea/templates/api/groups/bab7a3a8-2e30-4996-9405-48ca395b99c6/team, Request Method: PUT, Response Status Code: NotFound, Response Headers: Strict-Transport-Security: max-age=2592000
x-operationid: a228258204c3466dbd64c4d88373a416
x-telemetryid: 00-a228258204c3466dbd64c4d88373a416-82a9b5015f332574-01
X-MSEdge-Ref: Ref A: FC01DAADBD0D4A1A9ECBB9826707CC17 Ref B: DB3EDGE2518 Ref C: 2023-10-04T15:00:51Z
Date: Wed, 04 Oct 2023 15:00:52 GMT
ErrorMessage : {"errors":[{"message":"Failed to execute GetGroupMembersMezzoCountAsync.","errorCode":"Unknown"}],"operationId":"a228258204c3466dbd64c4d88373a416"}

Team-Enabling a Group

To team-enable a group, run the New-MgTeam cmdlet and provide a hash table containing information to allow Teams to find the new group (the Graph URI for the group) plus the Teams template to use. This code does the trick.

$GroupUri = "https://graph.microsoft.com/v1.0/groups('" + $NewGroup.Id + "')"
$NewTeamParams = @{
   "template@odata.bind"="https://graph.microsoft.com/v1.0/teamsTemplates('standard')"
   "group@odata.bind"="$($GroupUri)"
}
$NewTeam = New-MgTeam -BodyParameter $NewTeamParams
If ($NewTeam) {
   Write-Host ("Successfully team-enabled the {0}" -f $NewGroup.DisplayName)
}

Checking Groups Post-Creation

Figure 1 shows some of the dynamic Microsoft 365 groups created in my tenant. Note the groups for “Information Technology” and the “IT Department.” Obviously my checking of user departments was deficient prior to running the script. The fix is easy though. Decide on which department name to use and update user accounts to have that. Then remove the now-obsolete group. Entra ID will make sure that the accounts with reassigned departments show up in the correct group membership.

In this case, only one account had “IT Department,” so I quickly updated its department property with:

Update-MgUser -UserId Jack.Smith@office365itpros.com -Department "Information Technology"

I then removed the IT Department dynamic group:

$Group = Get-MgGroup -Filter "displayName eq 'IT Department Dynamic Group'"
Remove-MgGroup -GroupId $Group.Id

Soon afterwards, the membership of the Information Department Dynamic group was correct (Figure 2) and all was well.

You can download the complete script from GitHub. It would be easy to adapt the code to run as an Azure Automation runbook to scan for new departments and create groups as necessary.

Simple PowerShell Results in Big Benefits

Scripting the creation of dynamic Microsoft 365 groups for each department in a tenant isn’t too difficult. The membership rule is simple but could be expanded to include different criteria. Once the groups are created, they should be self-maintaining. That is, if you make sure that the department property for user accounts is accurate.

Learn how to exploit the data available to Microsoft 365 tenant administrators through the Office 365 for IT Pros eBook. We love figuring out how things like dynamic Microsoft 365 groups work.

Two Filters Available for the Entra ID Employee Hire Date Property

In an article published earlier this year about different ways to find Entra ID (Azure AD) user accounts with PowerShell, I commented that the Get-MgUser cmdlet could not apply a server-side filter against the Entra ID employee hire date property. For instance, to find accounts with an employee hire date, you must use Get-MgUser to fetch accounts and then apply a client-side filter to find the target objects. For instance, this code finds accounts with an employee hire date later than 1 January 2023:

[array]$Employees = Get-MgUser -filter "userType eq 'Member' and EmployeeId ge ' '" -Property Id, displayname, userprincipalname, employeeid, employeehiredate, employeetype
$CheckDate = Get-Date “8-Jul-2023”
$Employees | Where-Object {$CheckDate -as [datetime] -lt $_.EmployeeHireDate} | Sort-Object {$_.EmployeeHireDate -as [datetime]} -Descending | Format-Table DisplayName, userPrincipalName, employeeHireDate -AutoSize

DisplayName   UserPrincipalName                 EmployeeHireDate
-----------   -----------------                 ----------------
Michael King  Michael.King@office365itpros.com  01/08/2023 23:00:00
Terry Hegarty Terry.Hegarty@office365itpros.com 01/08/2023 23:00:00
Hans Geering  Hans.Geering@office365itpros.com  31/07/2023 23:00:00
Chris Bishop  Chris.Bishop@office365itpros.com  31/07/2023 23:00:00

The problem persists in the latest version of the Microsoft Graph PowerShell SDK using both the Get-MgUser and Get-MgBetaUser cmdlets.

Dynamic Groups Support for Employee Hire Date

All of which brings me to news that membership rules for Entra ID dynamic groups support the PowerShell le and ge operators against the employee hire date property. This capability is a preview for now.

In a nutshell, the new feature supports the creation of dynamic groups (which require Entra ID Premium P1 licenses) based on a filter against the EmployeeHireDate property. Two kinds of date filters are available. The first performs a simple comparison to test if the employee hire date is greater than or equal to or less than or equal to a specified date. For example, this command creates a dynamic Microsoft 365 group with a membership rule that finds all member accounts with an employee hire date greater or equal to 1 January 2023:

$Group = New-MgGroup -DisplayName "New Employees (Dynamic)" -Description "Dynamic group containing new employees (2023)" -MailEnabled:$True -SecurityEnabled:$False -MailNickname New.Employees.2023 -GroupTypes "DynamicMembership", "Unified" -MembershipRule "(user.employeehiredate -ge ""2023-01-01T00:00:00Z"" -and (user.usertype eq ""Member"")" -MembershipRuleProcessingState "On"

Dates must be passed in the sortable format rather than a more human-friendly type. For PowerShell, use Get-Date to set the date and format the output as follows:

$DateForFilter = (((Get-Date).AddDays(-365)) | Get-Date -format 'yyyy-MM-ddThh:mm:ssZ')

The second filter tests the employee hire date against a calculated date based on the current date. This example creates a dynamic Microsoft 365 group with a membership rule that looks for employees with hire dates within the last 31 days (system.now is the current date):

$Group = New-MgGroup -DisplayName "New Employees (Last Month)" -Description "Dynamic group containing employees hired in the last month" -MailEnabled:$True -SecurityEnabled:$False -MailNickname New.Employees.LastMonth -GroupTypes "DynamicMembership", "Unified" -MembershipRule "(user.employeehiredate -ge system.now -minus p31d ) -and (user.usertype eq ""Member"")" -MembershipRuleProcessingState "On"

It looks like only day intervals are supported. Entra ID rule validation rejects values like p4w (4 weeks) or p1m (1 month).

Validating the Filter Against the Entra ID Employee Hire Date Property

It’s easy to check the effectiveness of the membership rule. Let Entra ID calculate the membership for the dynamic group and note who’s present (Figure 1):

Then run the Get-MgUser example shown at the top of the article with an appropriate value inserted into the $CheckDate variable (use this code to set the variable to 31 days from the current date).

$CheckDate = (Get-Date).AddDays(-31)

Check the results generated by PowerShell against the set shown in the Entra ID admin center. The two should match. If they don’t, wait for 30 minutes or so to be sure that Entra ID has had time to process any recent updates and try again.

Time Updates All Cmdlets

It takes time for the Graph SDK cmdlets to catch up with new developments and preview features. Now that the Entra ID developers have enabled date filtering against the employee hire date property, it can’t be long before server-side filters work with Get-MgUser too. And if they don’t, there is a workaround – fetch the membership of the dynamic group with Get-MgGroupMember and use that information instead of running Get-MgUser. That’s the kind of lateral thinking we’re looking for in the great PowerShell script-off competition at TEC 2023 next month!

Support the work of the Office 365 for IT Pros team by subscribing to the Office 365 for IT Pros eBook. Your support pays for the time we need to track, analyze, and document the changing world of Microsoft 365 and Office 365.

Dynamic Distribution Lists to Dynamic Microsoft 365 Groups

Earlier this week, I described how to create a Microsoft 365 group and team from an Exchange Online dynamic distribution list. The code creates a group with static membership, but the input dynamic distribution list has its membership computed by Exchange Online using a recipient filter (aka a membership rule). Why can’t we take the filter used by the dynamic distribution list and apply it to create a dynamic Microsoft 365 group, which in turn becomes a team with dynamic membership. Well, as it turns out, it’s not quite as simple as taking a filter from one Microsoft 365 workload and using it in another.

Translating Recipient Filters for Dynamic Microsoft 365 Groups

Conceptually, it is possible to convert a dynamic distribution list to a be the membership rule for a dynamic Azure AD group. Two challenges exist: filter syntax and filter properties.

The query stored in a dynamic distribution list looks like this:

((((((Title -eq 'Architect') -or (Title -eq 'Senior Architect'))) -or (((Title -eq 'Principal Architect') -and (ExchangeUserAccountControl -ne 'AccountDisabled'))))) -and (-not(Name -like 'SystemMailbox{*')) -and (-not(Name -like 'CAS_{*')) -and (-not(RecipientTypeDetailsValue -eq 'MailboxPlan')) -and (-not(RecipientTypeDetailsValue -eq 'DiscoveryMailbox')) -and (-not(RecipientTypeDetailsValue -eq 'PublicFolderMailbox')) -and (-not(RecipientTypeDetailsValue -eq 'ArbitrationMailbox')) -and (-not(RecipientTypeDetailsValue -eq 'AuditLogMailbox')) -and (-not(RecipientTypeDetailsValue -eq 'AuxAuditLogMailbox')) -and (-not(RecipientTypeDetailsValue -eq 'SupervisoryReviewPolicyMailbox')))

We know this is a custom recipient filter created using PowerShell because the properties it uses are not covered by the precanned filters created using EAC. The custom filter comes first followed by a bunch of exclusions inserted by Exchange to make sure that system mailboxes are not in the returned set. Exchange adds these exclusions automatically when it saves the recipient filter for a dynamic distribution list.

It’s technically possible to take a recipient filter from a dynamic distribution list and parse it to extract the custom part using Regex expressions. By using a function to remove special characters, I was able to process the recipient filter shown above like this:

$Filter = (Get-DynamicDistributionGroup -Identity "System Architects").RecipientFilter
$i = $Filter.IndexOf("-and (ExchangeUser")
$f = $Filter.Substring(0,$i)
$ExoFilter = Remove-StringSpecialCharacter -String $f -SpecialCharacterToKeep '-', " "

The output is:

Title -eq Architect -or Title -eq Senior Architect -or Title -eq Principal Architect

However, a complicating factor is that Exchange has changed the format of the exclusions it inserts over time. This means that you can never be sure how the recipient filter is formatted, and my code didn’t work when tested against several other dynamic distribution lists in my tenant, some of which go back to 2014.

In any case, the output I generated isn’t a valid Azure AD filter, and some additional work is needed to make it work with a dynamic Azure AD group (team). Briefly:

• Title is the name of the Exchange property. It is JobTitle in Azure AD. Also, user properties are prefixed with “User,” meaning that you end up with User.JobTitle.
• The -eq and -or operators in Exchange lose the leading hyphen in Azure AD.

Different Filterable Properties

A more fundamental issue is that while Exchange supports many mail-enabled properties for custom recipient filters in dynamic distribution lists, the set of filterable properties don’t match the set available for Azure AD. You might be able to convert some queries, but you won’t be able to convert others. The difference is accounted for by the fact that Exchange queries against its own directory, which stores details of mail-enabled objects, while Azure AD queries its directory. The two directories have different schemas.

Once I realized the extent of the incompatibility between the two sets of properties, I stopped trying to figure out how an automatic conversion could be done. Too much time would be needed to figure out the permutations and combinations involved in formatting membership rules. And given the number of times a conversion might be necessary, the easiest solution is to let human administrators generate the membership rules.

Previewing Azure AD Filters

The GUI in the Azure AD admin center to deal with dynamic groups include a rules editor. You can paste the outline of a membership rule taken from an Exchange dynamic distribution list and modify it there. The Azure AD admin center also includes a nifty preview feature to validate that a membership rule works. After making whatever changes are necessary to create a valid rule for Azure AD, you can test the rule by nominating one or more users that you know should match the membership rule. Click the validate button and Azure AD will tell you if the directory can find the users you selected using the rule (Figure 1).

Exchange Online doesn’t have a similar way to validate the membership of a dynamic distribution list. Maybe that’s why Microsoft considers dynamic Azure AD groups to be a premium feature and charges accordingly.

Creating a Dynamic Azure AD Group with PowerShell

For the record, you can create a dynamic Azure AD group with PowerShell. In this instance, I use the New-MgGroup cmdlet from the Microsoft Graph PowerShell SDK (the New-AzureADMSGroup cmdlet from the preview version of the Azure AD module will work too). The important point is that the group has dynamic membership rather than static and has a rule to control the membership:

$Group = New-MgGroup -DisplayName "System Architects (Dynamic x2)" -Description "People with an architect job title" -MailEnabled:$True -SecurityEnabled:$True -MailNickName "System.Architects.Dynamic2" -GroupTypes "DynamicMembership", "Unified" -MembershipRule "(User.JobTitle -eq ""Architect"" or  User.JobTitle eq ""Senior Architect

After creating the dynamic Azure AD group, you can team-enable it with the New-Team cmdlet by passing the identifier of the newly created group.

New-Team -GroupId $Group.Id

Incompatible schemas, properties, and syntax might stop the automatic conversion of membership rules, but you can at least get the job done with a little manual effort.

Learn more about how the Office 365 applications really work on an ongoing basis by subscribing to the Office 365 for IT Pros eBook. Our monthly updates keep subscribers informed about what’s important across the Office 365 ecosystem.

Dynamic Expansion of Recipient Lists

Exchange 2003 introduced query-based distribution groups (QDGs), a form of email distribution list which doesn’t have a fixed set of recipients but instead contains a query to be executed against a directory to resolve the recipients each time the list is used. Today, the same concept persists in Exchange Online dynamic distribution lists (DDLs) and Microsoft 365 dynamic groups. However, as detailed in Table 1, the two implementations for dynamic membership are based on very different foundations.

You can boil the differences down to the directory used to resolve membership, but that’s a very simplistic view. The bigger differences are the cost and how Microsoft 365 groups are used to manage membership for Teams, Yammer, and other apps.

Anatomy of a Dynamic Distribution List

A DDL is composed of:

• An Exchange Online object which is not synchronized to Azure AD. A DDL only exists in EXODS.
• A recipient filter used to resolve the set of recipients. The filter can resolve against Azure AD attributes (like City and Department), but only if they are synchronized to EXODS. Many other Exchange-specific attributes can be used in recipient filters.
• Other properties like a manager, MailTip, etc. used by email functionality.

A DDL cannot be used for security purposes. Its membership cannot contain a mixture of fixed and dynamic recipients, but membership can be made up of any mail-enabled recipient type including other distribution lists, mail contacts, public folders, and hybrid recipients.

Managing Dynamic Distribution Lists

DDLs are created and managed using the older Exchange admin center or PowerShell. The modern EAC does not yet include the functionality to create and manage DDLs. And because DDLs are not Azure AD objects, you can’t create or manage them through the Azure AD portal or the Microsoft 365 admin center.

Figure 1 shows the initial step in creating a new DDL. At the bottom of the screen you can see the start of creating the query for the DDL when we specify what types if mail-enabled recipients should be found.

Finding only recipients of a certain type is a valid query, but in most cases, you’ll want to refine the filter by adding some rules to check against filterable properties. In Figure 2, we’ve chosen to filter against two properties (Department and CustomAttribute1) and are entering one of the values we want to find in CustomAttribute1.

When saved, the rules are written out into the RecipientFilter property of the DDL. Exchange Online writes the recipient filter into the list after applying some post-processing to make sure that the filter finds the intended objects. Here’s the filter created for the DDL shown in Figures 1 and 2:

Get-DynamicDistributionGroup -Identity "Office 365 for IT Pros Writers" | Select -ExpandProperty RecipientFilter

((((((Department -eq 'Writers') -or (Department -eq 'Authors') -or (Department -eq 'Production'))) -and (CustomAttribute1 -eq 'Author’) -and (RecipientType -eq 'UserMailbox'))) -and (-not(Name -like 'SystemMailbox{*')) -and (-not(Name -like 'CAS_{*')) -and (-not(RecipientTypeDetailsValue -eq 'MailboxPlan')) -and (-not(RecipientTypeDetailsValue -eq 'DiscoveryMailbox')) -and (-not(RecipientTypeDetailsValue -eq 'PublicFolderMailbox')) -and (-not(RecipientTypeDetailsValue -eq 'ArbitrationMailbox')) -and (-not(RecipientTypeDetailsValue -eq 'AuditLogMailbox')) -and (-not(RecipientTypeDetailsValue -eq 'AuxAuditLogMailbox')) -and (-not(RecipientTypeDetailsValue -eq 'SupervisoryReviewPolicyMailbox')) -and (-not(RecipientTypeDetailsValue -eq 'GuestMailUser')))

The filter looks complex, but the bulk is made up of exclusionary clauses to avoid messages being sent to system mailboxes.

Recipient Filters

Recipient filters (queries) are at the heart of DDLs. The queries are stated in OPATH format and two types are available:

• Precanned filters are created when you compose query rules for a DDL through the EAC. Precanned filters are restricted to queries against a small number of well-known object properties such as the department, city, and 15 customizable attributes. See this article for details for how to use precanned filters.
• Custom filters are created when you use PowerShell to define a recipient filter. Canned filters are more powerful and flexible than precanned filters because a wider of properties can be included in a query. Once you apply a custom filter to a DDL, you won’t be able to edit the filter through the EAC. This article explains how to build custom filters for use with a dynamic distribution list.

No matter how good your query is, it is useless if the properties of objects stored in EXODS are incomplete or inaccurate. Queries will run, but the transport service won’t find the correct set of addressees to receive messages.

You can test the effectiveness of a recipient filter by using it with the Get-Recipient cmdlet and checking the set of objects returned. For example:

Get-Recipient –RecipientPreviewFilter (Get-DynamicDistributionGroup –Identity "Office 365 for IT Pros Writers").RecipientFilter

Name		RecipientType
---- 		-------------
Jeff.Guillet    UserMailbox
James.Ryan      UserMailbox
Jane.Sixsmith   UserMailbox

Update: You can now use the Get-DynamicDistributionGroupMember cmdlet to see the membership of a dynamic distribution list.

Messages sent to dynamic distribution lists with queries that don’t find any recipients go into a void. Senders don’t receive any indication that the message reached no one, which is a good reason to validate that the recipient filter for a DDL finds some recipients.

Dynamic Distribution Lists Still Valuable

DDLs are simple, robust, and work. Everything depends on the recipient filter, but once you can query and find the right recipients, there’s very little else that can go wrong. DDLs are a good choice when you want to target communications at a changeable set of mail-enabled recipients and don’t want to spend a lot of time making sure that the list membership doesn’t go out of date. The big dependency is the directory. Make sure that EXODS (and by extension, Azure AD) is populated with accurate information and you’ll lay a great foundation for successful DDLs.

Learn more about dynamic distribution lists and dynamic Microsoft 365 Groups in the Office 365 for IT Pros eBook. We must be like a dynamic distribution list because we’re always updating our contents to stay accurate.