Recovering Deleted Groups with the Graph PowerShell SDK

Restore Soft-Deleted Groups Back to Good Health

Updated 23 Feb 2024

In another article, I cover how to recover soft-deleted user accounts using the Microsoft Graph PowerShell SDK. The topic of how to restore deleted Entra ID 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 in March 2024.

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 Microsoft 365 groups. Soft-deleted groups remain in the Entra ID recycle bin for 30 days following their deletion. After this period lapses, Entra ID permanently removes the groups. Remember that even after Entra ID 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 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.

Update: The script now uses the Get-MgDirectoryDeletedItemAsGroup cmdlet. The code has been tested against V2.15 of the Microsoft Graph PowerShell SDK.

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

Connect-MgGraph -Scopes Directory.Read.All, Group.ReadWrite.All
[array]$SoftDeletedGroups = Get-MgDirectoryDeletedItem -DirectoryObjectId Microsoft.graph.group
[array]$DeletedGroups = Get-MgDirectoryDeletedItemAsGroup -All
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 Entra ID Groups

After finding the identifier of the group to restore, use it with the Restore-MgDirectoryDeletedItem cmdlet to move the group object from the 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 Entra ID, Teams, and OWA and a little longer before SharePoint Online fully synchronizes the new state reported by Entra ID. 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 group. The Microsoft 365 admin center and Entra admin center (Figure 2) both include options to restore deleted 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 Entra ID 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.