Recovering Deleted Groups with the Graph PowerShell SDK

Restore Soft-Deleted Groups Back to Good Health

In another article, I cover how to recover soft-deleted Azure AD accounts using the Microsoft Graph PowerShell SDK. The topic of how to restore deleted Azure AD groups (including Microsoft 365 groups) came up in discussion recently, and I realized that I don’t cover this point very well when discussing basic group management with the Microsoft Graph PowerShell SDK. This article addresses that deficiency and hopefully helps people update scripts before the deprecation of the Azure AD and Microsoft Online Services modules next June.

Find Soft-Deleted Groups

The same approach used with soft-deleted user accounts applies when restoring soft-deleted groups:

1. Find the set of soft-deleted groups. Soft-deleted groups remain in the Azure AD recycle bin for 30 days following their deletion. After this period lapses, Azure AD permanently removes the groups. Remember that even after Azure AD removes the group object, if the group comes within the scope of one or more Microsoft 365 retention policies, group resources (like the group mailbox and SharePoint site) remain available until the last retention period lapses.
2. Select the group to restore. You need the group identifier (GUID) to restore a group.
3. Restore the group. Groups that don’t have any connected resources should become available very quickly after restoration. Microsoft 365 groups with connected resources like a team, SharePoint Online site, and Planner plans need more time for individual workloads to reconnect everything back to the restored group.

Here’s some code to report the set of soft-deleted groups in the Azure AD recycle bin. The Get-MgDirectoryDeletedItem cmdlet returns a set of soft-deleted directory objects matching the object type (microsoft.graph.group). The cmdlet output appears blank, but the set of objects is in an array called Value in the AdditionalProperties property.

Why the cmdlet works in this manner is beyond me. Some justify the output with the statement that “it’s how the Graph API to list deleted items works.” That assertion is true, but just because an underlying API works in an odd manner is no reason to perpetuate the behavior in a cmdlet. I hope that Microsoft improves how cmdlets used for day-to-day Azure AD management work in V2.0 of the SDK, due later this year.

After we find the set of soft-deleted groups, it’s easy to extract the information and calculate how long remains before Azure AD deletes the group permanently.

Connect-MgGraph -Scopes Directory.Read.All, Group.ReadWrite.All
[array]$SoftDeletedGroups = Get-MgDirectoryDeletedItem -DirectoryObjectId Microsoft.graph.group
[array]$DeletedGroups = $SoftDeletedGroups.AdditionalProperties['value']
If ($DeletedGroups.count -eq 0) { Write-Host "No recoverable groups can be found - exiting"; break}
$Report = [System.Collections.Generic.List[Object]]::new(); $Now = Get-Date
ForEach ($Group in $DeletedGroups) {
     [datetime]$DeletedDate = $Group.deletedDateTime
     $PermanentRemovalDue = Get-Date($DeletedDate).AddDays(30)
     $TimeUntilRemoval = $PermanentRemovalDue - $Now
     $ReportLine = [PSCustomObject]@{ 
          Group                = $Group.displayName
          Id                   = $Group.id
          Deleted              = $Group.deletedDateTime
          PermanentDeleteOn    = Get-Date($PermanentRemovalDue) -format g
          DaysRemaining        = $TimeUntilRemoval.Days } 
       $Report.Add($ReportLine) 
}
$Report | Sort-Object {$_.PermanentDeleteOn -as [datetime]} | Out-GridView

Figure 1 shows some typical output. The Id property is the group identifier.

Restore Deleted Azure AD Groups

After finding the identifier of the group to restore, use it with the Restore-MgDirectoryDeletedItem cmdlet to move the group object from the Azure AD recycle bin and make it available to users:

Restore-MgDirectoryDeletedItem -DirectoryObjectId 4e9393c3-67e9-4f95-a0df-70103a667c0a

It can take a few minutes before the restored group shows up in Azure AD, Teams, and OWA and a little longer before SharePoint Online fully synchronizes the new state reported by Azure AD. Depending on service load, everything should be fully connected within an hour.

Admin Consoles and Group Restoration

Remember that you don’t need to use PowerShell to restore a deleted Azure AD group. The Microsoft 365 admin center and Azure AD admin center (Figure 2) both include options to restore deleted Azure AD groups, and the Manage groups section of OWA has the option for group owners to restore a deleted Microsoft 365 group that they own. These options use the same techniques to list soft-deleted groups and restore a selected group. OWA is slightly different because it applies a filter to find groups owned by the user.

In general, I use an admin center whenever I need to restore deleted Azure AD groups and revert to PowerShell when I need to do something special, such as a mass restoration of groups or to create reports about groups due for permanent deletion in the next seven days. It’s good to understand the technology behind a GUI and always nice to have the option to perform an action with PowerShell when the need arises.

---

Learn how to exploit the full set of capabilities available to Microsoft 365 tenant administrators through the Office 365 for IT Pros eBook. We love figuring out how things work.