PowerShell scripts for managing Microsoft 365 components
Master Key for the Cloud
Different components of Microsoft 365 use different portals for managing services such as Teams, SharePoint, and Exchange, making administration difficult. With an arsenal of scripts and the appropriate PowerShell modules, however, many recurring activities can be conveniently controlled from the command line.
Many companies use Microsoft Teams when it comes to enterprise collaboration. The system relies on Microsoft 365 Groups to assign permissions in Exchange, SharePoint, and in itself and to control its functions. Microsoft 365 Groups are stored in Azure AD and are managed there – including the memberships for internal and external users. It's a good idea to start with Groups.
Controlling Microsoft 365 Groups
A new Microsoft 365 group can act as a team in different ways. You can either take the Exchange PowerShell approach with
Connect-ExchangeOnline -userPrincipalName <user@example.com> New-UnifiedGroup -DisplayName "<groupname>" -Alias "<groupalias>" -Owner <user@example.com>
or use the Azure AD PowerShell modules:
Connect-AzureAD New-AzureADMSGroup -DisplayName "<groupname>" -MailNickname "<groupalias>" -GroupTypes "Unified" -MailEnabled $true-SecurityEnabled $true
The Unified
group type identifies the Microsoft 365 groups that are used for Teams and Yammer, as well as permissions and mailing. Azure AD PowerShell distinguishes between the New-AzureADGroup
and New-AzureADMSGroup
cmdlets for traditional and Microsoft 365 groups, respectively.
If you have not installed the Exchange Online PowerShell cmdlets, do so in a PowerShell session as administrator and import the module as a normal user:
Install-Module ExchangeOnlineManagement Import-Module Exchange-OnlineManagement
You need to be aware of one difference between the Exchange and Azure AD ways of creating groups. If you take the Exchange route, you create an associated mailbox for the group directly, whereas in Azure AD (AAD) you first initiate the creation in the directory and then create the mailbox after AAD and Exchange are synchronized.
For example, for a new sales campaign, you can easily add staff from one campaign who are already members of a team as members of the new team:
Get-AzureADGroupMember -ObjectId e45712da-4a52-422c-94c3-b158d366945a | % { Add-AzureADGroupMember -ObjectID 378f9975-143d-418d-b735-96ab403e75f9 -RefObjectId $_.ObjectId }
This command first reads the members of the old campaign and then writes them to the new team (identified by ObjectID
). In the foreach loop (starts with %
), each member is considered and passed as RefObjectID
.
Group owners who do not play a central role in the life cycle of traditional groups (e.g., from Windows AD) are particularly important in Teams. The owners can configure the team in detail and are the contact persons for reviews of members:
Add-AzureADGroupOwner -ObjectId 7615d111-e04b-493a-9992-dca9493828fd-RefObjectId (Get-AzureADUser -SearchString <User@example.com>).ObjectId Get-AzureADGroupOwner -ObjectId 7615d111-e04b-493a-9992-dca9493828fd
Groups that have fewer than one owner need closer attention. The command
Get-AzureADMSGroup -Filter " groupTypes/any(c:c eq 'Unified')"-All:$true | ? { (Get-AzureADGroupOwner-ObjectId $_.Id).Count -lt 1 } | Export-CSV C:\temp\missing-owners.csv
finds more owners and defines them.
Managing Guest Access to the Tenant
Before you create many teams and groups, you need to familiarize yourself with the tenant settings. Guest access for external users is now allowed as a basic configuration in Microsoft Teams. If you want to make Microsoft 365 groups or teams inaccessible to external users, you can use an AAD setting that you copy as a template and then apply to the groups. This also works the other way around if you want to prohibit guest access with the tenant settings but allow external members of individual teams:
$template = Get-AzureADDirectorySettingTemplate | ? {$_.displayname-eq "group.unified.guest"} $preventGuests = $template.CreateDirectorySetting() $preventGuests["AllowToAddGuests"]=$false
Then, apply the setting to the groups that will no longer be able to include external members:
Get-AzureADMSGroup -Filter "groupTypes/any(c:c eq 'Unified')"-All:$true | ? {$_.displayName -like "Finance*" } | % { New-AzureADObjectSetting -TargetType Groups -TargetObjectId $_.Id -DirectorySetting $preventGuests }
The command first searches for all Microsoft 365 groups with the prefix Finance and then applies the settings.
Controlling Groups with Labels
Labels from the Security and Compliance Center are more elegant and better automated (Figure 1). These labels can be used in many different places in the Microsoft Cloud, are not only used to encrypt email, and can classify and restrict memberships of teams. To use the labels in Azure AD for groups, you first need to enable the labels:
$template = Get-AzureADDirectorySettingTemplate | ? {$_.displayname -eq "group.unified"} $copy = $template.CreateDirectorySetting() $copy["EnableMIPLabels"] = $true New-AzureADDirectorySetting -DirectorySetting $copy
Next, create a new label with the appropriate cmdlet from the Exchange Online PowerShell modules. However, the commands first need to connect to the Information Protection (IP) endpoint, assume the role of a compliance admin, and define a new label (Listing 1). The last command comprises two parts: creating the label and the additional information in LabelActions
that defines the label's rules about group memberships and creating permissions for external guests.
Listing 1
New Label
Connect-IPPSSession -UserPrincipalName <compliance-admin@frickelsoftnet.onmicrosoft.com> New-Label -DisplayName "FSFTTopSecret" -Name "<Frickelsoft top secret>" -Tooltip "<This is a confidential file>" -LabelActions '{"Type":"protectgroup","SubType":null,"Settings":[{"Key":"privacy","Value":"private"},{"Key":"allowemailfromguestusers","Value":"false"},{"Key":"allowaccesstoguestusers","Value":"false"},{"Key":"disabled","Value":"false"}]}'
In this example, groups classified with the label can only be joined with the owner's permission (privacy: private
), and external members are not allowed (allowaccesstoguestusers: false
). For deployment, you assign the label (often together with other labels in a production environment) to a label policy and trigger the synch between Exchange and the Compliance Center for Azure AD:
New-LabelPolicy -Name "<policyname>" -Labels "<secretfiles>" Execute-AzureADLabelSync
The label should reach Azure AD after a few minutes.
Finally, it's time to pin one of the labels on an existing or new Microsoft 365 group. To connect the label and the team, you need the unique ID of the label; you can display an overview of all labels and each immutableID
with PowerShell:
Get-Label | ft ImmutableID, Name
The table output from the command provides the assignment of the IDs to the label names; you then use the ID of the correct label with the LabelID
property when you create or modify the team:
New-AzureADMSGroup -DisplayName " <groupname>" -MailNickname " <groupalias>" -GroupTypes "Unified" -MailEnabled $true -SecurityEnabled $true -LabelId f460a5b0-8d8e-4ac1-bb92-afb9ea22f9da
If you followed the steps and created the LabelActions
as shown in the example, the labeled team will no longer accept new members from other tenants.
Buy this article as PDF
(incl. VAT)