Issue Affects Directory API Cmdlets

In a March 2025 article, I discuss how to use the Microsoft Graph PowerShell SDK to restore deleted user accounts. Two methods are supported: restore an account to its original state and restore an account and change its user principal name. This feature allows a restored account to have a new user principal name with an amended given name, surname, or domain.

The trouble is that a change made to several Microsoft Graph directory APIs to add optional body parameters that did not previously have a body. This had a knock-on effect (tracked here) for anything based on .Net (like the Microsoft Graph PowerShell SDK) because the underlying method had to be changed from one without a body parameter to one with a body parameter. This kind of change can break the process used to generate the Microsoft Graph PowerShell SDK, so body parameters are now excluded for cmdlets generated from the affected APIs until Microsoft can fix the underlying issue.

Restore Deleted User Accounts with a New User Principal Name

The problem surfaces in the Restore-MgBetaDirectoryDeletedItem cmdlet when it restores a deleted account with a new user principal name because the cmdlet uses a hash table containing details of the new user principal name to pass a request body in the body parameter. No body parameter means that the cmdlet loses its ability to give the restored account a new user principal name. The SDK bug is tracked here.

Versions of Microsoft Graph PowerShell SDK generated before the change took effect retain the ability to run Restore-MgBetaDirectoryDeletedItem -BodyParameter to restore deleted user accounts. The last version I used for this task is V2.25, but it’s possible that a subsequent version will work. I can say that the version of the cmdlet in the latest version of the SDK (V2.34) does not have the parameter, so a different approach is necessary. Fortunately, the workaround is easy: instead of Restore-MgBetaDirectoryDeletedItem, use the Invoke-MgGraphRequest cmdlet to run the Graph API request. Exactly the same hash table can be passed as a request body.

The Adjusted Code to Restore Deleted User Accounts with a New User Principal Name

The necessary adjustments are simple. Literally, it’s a matter of swapping out the call to Restore-MgBetaDirectoryDeletedItem and replacing it with two lines. The first is the URI to pass, pointing to the deletedItems endpoint with the object identifier of the account to restore. The second runs Invoke-MgGraphRequest to post the request body (hash table) to the endpoint. Here’s the code:

$DeletedUserUPN = Read-Host “Enter the User principal name of the deleted account”
$NewUserPrincipalName = Read-Host “Enter the new User principal name”

$Headers = @{}
$Headers.Add("consistencylevel","eventual")
$DeletedObject = Get-MgDirectoryDeletedItemAsUser -Filter "endsWith(UserPrincipalName,'$DeletedUserUPN')" -Headers $Headers -CountVariable OutCount

If ($DeletedObject) { 
  # Details for new user principal name
  $NewUPNDetails = @{}
  $NewUPNDetails.Add("newUserPrincipalName",$NewUserPrincipalName)
  $NewUPNDetails.Add("autoReconcileProxyConflict",$true)
  Write-Host "Restoring Object with new User Principal Name"
  $Uri = ("https://graph.microsoft.com/beta/directory/deletedItems/{0}/restore" -f $DeletedObject.Id)  
  $Status = Invoke-MgGraphRequest -Uri $Uri -Method Post -Body $NewUPNDetails
  If ($Status) { 
    Write-Host ("Account restored for {0} with UPN of {1}" -f $DeletedObject.displayName, $NewUserPrincipalName)
    # Update the primary SMTP address for the account with the new UPN
    Update-MgUser -UserId $deletedObjectId -Mail $NewUserPrincipalName
  }
} Else {
  Write-Host ("Can’t find the {0} deleted account" -f $DeletedUserUPN)
}

An Unfortunate Break

Just when it seemed safe to embrace the Microsoft Graph PowerShell SDK fully after last year’s shenanigans, something like this comes along, even for beta cmdlets. The SDK developers are blameless here. They are simply reacting to a change that took place elsewhere in the Microsoft development firmament. Unfortunately, removing the body parameter will break any script that calls one of the affected cmdlets. All you can do is test, and if you run into a problem, the fix is easy.

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. Only humans contribute to our work!

New UX Returns Content Searches to their Original State

The announcement in message center notification MC1216266 (9 January 2026) of a change to the content search feature in the Purview eDiscovery solution didn’t come as a surprise. In a nutshell, Microsoft is restricting the functionality of content searches to make them a simple find and export mechanism. If eDiscovery administrators want to use full eDiscovery features, like creating review sets and holds, they must create full-blown eDiscovery cases. The change is effective from February 16, 2026.

The History of Content Searches

Some history can explain why Microsoft is making the change. Originally, following the transition from the workload-specific eDiscovery systems in Exchange Online and SharePoint Online, three separate eDiscovery components existed in Microsoft 365: eDiscovery standard (E3), eDiscovery Premium (a high-end eDiscovery product bought from Equivio in 2015 and included in Office 365 E3), and content searches. Clearly, this was a recipe for overlap and wasted engineering effort.

Microsoft’s solution was to modernize eDiscovery by creating a single eDiscovery framework to support the three existing mechanisms. The functionality differences for the standard and premium solutions could be controlled by the user interface, which only reveals features if a user has the right license. Although this approach works well for standard and premium eDiscovery, content searches didn’t fit into the new framework.

To solve the problem, Microsoft created a special eDiscovery case and added the existing content searches as case searches. In other words, if you look at the special content search case, you see multiple searches – one for every previous standalone content search. This isn’t an issue for the eDiscovery framework because its architecture has always supported multiple searches per case. The idea worked and the transition of content searches to the new eDiscovery occurred in May 2025.

How Administrators Use Content Searches

Purview eDiscovery is a highly functional solution intended to meet the needs of eDiscovery investigators who might have to process millions of emails and files. Content searches have traditionally been used by administrators for much simpler purposes, such as finding messages that an organization wishes to purge with a compliance search action or (as in Figure 1), finding if a user sent a specific Teams chat message.

However, because content searches had become eDiscovery case searches, they gained a heap of functionality that isn’t needed for simple searches that just gets in the way. For example, adding a review set (of items found by a search) is inappropriate. If investigators want to perform deep-dive analysis on items, they should use a full eDiscovery case. The same is true for eDiscovery in-place holds.

Microsoft is therefore introducing a simplified interface that reflects how administrators use content searches. You’ll still be able to search and find items, and export those items if necessary (for instance, to create an archive for all items owned by a specific user). That’s enough for most content searches. If any more features are needed, create an eDiscovery case.

Applying an Expiration Period to Exports of Search Results

Speaking of eDiscovery cases, another change (MC1217141, 13 January 2026) happening on February 2026 will see a 14-day expiration period applied to the Azure blob containers used to hold export data found by searches, including content searches. The limit doesn’t apply to the containers used for review set exports.

The idea behind the change is simple. The results of searches performed against a dynamic environment like Microsoft 365 change over time. If you download export results some days after a search completes, the results are likely to be incomplete and will become increasingly incomplete over time. Applying a 14-day expiration period is a balance between usefulness and accuracy. However, my advice is to export data as soon as possible after searches complete, just to be sure that any review is conducted against current information (or as close as you can get to it).

Learn how to use Purview eDiscovery and to exploit the data available to Microsoft 365 tenant administrators through the Office 365 for IT Pros eBook. We love figuring out how things work.

New Entra ID Role Highlights Need to Manage Role Assignments

The announcement in MC1215071 (8 January 2026) that a new Entra ID administrative role called Teams External Collaboration Administrator will roll out in late January 2026 made me wonder if too many administrative roles are now available for Microsoft 365 tenants.

Conceptually, I don’t have anything against the idea of creating a special role to assign to people who manage the external collaboration settings for Teams. However, on a practical level, I question whether the role will get much use. I mean, how often does a tenant need to update its external collaboration settings? The changes that are normally made to external collaboration, such as adding an external domain to the list permitted for federated chat and meetings, are hardly so earth shatteringly onerous that a “normal” Teams administrator can’t perform the task in a few minutes (using the newly simplified Teams admin center interface for external collaboration, of course).

The other thing is that the majority of Microsoft 365 tenants are not large enough to have the need for a dedicated administrative role to handle Teams external collaboration. One person (called the global administrator) probably does everything. In short, the change described in MC1215071 is for very large enterprise tenants with big administrative staffs and clearly delineated areas of responsibility. That’s fine too – large tenants should get some love.

Entra ID Roles Assigned in a Tenant

Getting back to my original thought, the number of directory role templates in my tenant is currently 133, soon to be 134 when the Teams external collaboration administrator role arrives. A role template defines what rights a role holds and the set of templates defined by Entra ID are called built-in roles. The first time a role is assigned within a tenant (by an administrator or when configuring an application), it becomes an assigned role. My tenant only uses 39 assigned roles:

$Roles = Get-MgDirectoryRoleTemplate -All
$Roles.Count
133
$AssignedRoles = Get-MgDirectoryRole -All
$AssignedRoles.count
39

$AssignedRoles | Sort-Object DisplayName | Format-Table DisplayName, id

For the record, the tenant reported 31 assigned roles in March 2022 when I reviewed how to assign roles to user accounts with the Microsoft Graph PowerShell SDK.

Unwanted or Disused Entra ID Roles

Some of the roles are present due to testing, and some belong to now-deprecated solutions. For example, the Knowledge administrator and Knowledge manager roles are associated with Viva Topics, introduced in March 2021 and retired in February 2025. These roles and their assignments live on as tombstones for the departed solution.

In a rush to embrace granular management, my tenant has roles that probably don’t get much use and many of the roles are utterly devoid of members. Message Center reader for instance, or Hybrid identity administrator (the tenant left hybrid status a long time ago). Skype for Business administrator is another belonging to a retired application, and I suspect that Yammer administrator (Viva Engage) doesn’t get much use. The Insights administrator and Insights Business leader roles were never used because the tenant doesn’t use Viva Insights. However, I probably looked at the application in the past and that was probably enough to cause the roles to appear in the tenant.

The point is that a small set of roles is enough to segregate administrative tasks for many Microsoft 365 tenants. My guess is that ten roles are sufficient in most cases:

• Global administrator.
• Teams administrator.
• SharePoint administrator.
• Exchange administrator.
• User administrator.
• Groups administrator.
• Reports reader.
• Compliance administrator.
• Device managers.
• Billing administrator.

These are highly privileged roles. Many of the other 124 roles that exist are there to allow work to be done without a high level of permissions. Assigning very precise roles to user accounts works great in large tenants but might be overkill in smaller establishments.

Audit Roles and Role Membership

Elsewhere, I made the case that January is a great time to audit the subscriptions and licenses for Microsoft 365 tenants. The same is true for Entra ID roles and assignments. Check the roles that are in use and the users who are members of the role groups. This is simple to do with the PowerShell script referenced in this article, which handles both direct and PIM role assignments. Figure 1 shows some sample output from the script.

After reviewing current assignments, consider removing members from roles:

• That are no longer in active use.
• When the member no longer needs to use the role.

For example, I ran this code to find the current assigned members for the Knowledge manager role.

[array]$Members = Get-MgDirectoryRoleMember -DirectoryRoleId ea669ded-edb0-4c95-a340-d7c2ae58ba3b
$Members.additionalProperties.displayName
Ben Owens (DCPG)
Sean Landy

You can’t delete a built-in Entra ID role. However, you can remove all the members from a role through the Entra admin center or with PowerShell. Scripting is easier when a role has many members. Here’s how:

$Template = Get-MgDirectoryRole -Filter "displayName eq 'Knowledge Manager'"
$TemplateId = $Template.Id
[array]$Members = Get-MgDirectoryRoleMember -DirectoryRoleId $TemplateId

ForEach ($Member in $Members) {
  $UserId = $Member.Id
  $Uri = ("https://graph.microsoft.com/v1.0/directoryRoles/roleTemplateId={0}/members/{1}" -f $TemplateId, $UserId)
  Invoke-MgGraphRequest -Uri $uri -Method Delete
}

The Microsoft Graph PowerShell SDK includes a Remove-MgDirectoryRoleMemberByRef cmdlet, but the cmdlet isn’t working so well in V2.34. However, the Remove-MgRoleManagementDirectoryRoleAssignment cmdlet does work, but in this case I chose to show how the Invoke-MgGraph cmdlet proves its usefulness by executing the underlying Graph API request when a cmdlet isn’t available or a cmdlet doesn’t work as expected.

In addition to Entra ID roles, consider auditing the assignments for Purview (compliance) role groups.

Power and Responsibility

I question the number of available Entra ID roles only to raise awareness about role management. It’s good to have the ability to manage access to functionality at a granular level, but with great power comes great responsibility, which means that tenants should keep an eye on role membership.

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 work.

RCD an Essential Tool for Tenants with Microsoft 365 Copilot

In April 2025, I discussed how the SharePoint Online Restricted Content Discovery (RCD) feature works. In a nutshell, RCD blocks site content from Microsoft 365 Copilot, meaning that Copilot isn’t allowed to use site content in its responses. Because RCD limits SharePoint Search, content also doesn’t appear in organization-wide search results (Figure 1).

RCD is licensed through SharePoint Advanced Management (SAM) and is one of the SAM features available to tenants with Microsoft 365 Copilot licenses. Given that all tenants store some form of confidential or sensitive information in SharePoint Online, RCD is something that tenants with Microsoft 365 Copilot should deploy to prevent the potential of inadvertent leakage of that information.

Applying RCD

Until recently, RCD was controlled by SharePoint administrators, who can apply RCD to a site through the SharePoint admin center (Figure 2) or with PowerShell.

Administrators are used to taking responsibility, and enabling RCD for a site is usually a one-time operation. However, given the number of SharePoint sites in use (largely because of Teams), controlling RCD for a medium to large tenant can rapidly become a time soak.

Fortunately, Microsoft listened to customer feedback and has introduced the ability for site administrators to enable and disable RCD for their sites. The feature achieved general availability in early January 2026 and is documented here.

Allowing Site Administrators to Control RCD

Before site administrators can control RCD, the tenant must be enabled for what Microsoft calls delegated content discoverability. This is done by updating a tenant setting with PowerShell. When dealing with new features, it’s usually true that the latest version of the Microsoft.Online.SharePoint.PowerShell module is required, so I installed version 16.0.26712.12000 from the PowerShell gallery and then ran:

Set-SPOTenant -DelegateRestrictedContentDiscoverabilityManagement $true

Enabling RCD for a Site

Like all changes to SharePoint Online settings, it can take some time before the update is effective across a tenant. When delegated RCD is available, it appears in the Site Information panel under the heading Restrict content from M365 Copilot (Figure 3). If the site administrator changes the setting, they’re required to provide a justification similar to when downgrading a sensitivity label for a file.

SharePoint Online generates audit records when a site administrator enables or disables RCD for a site. Here’s some PowerShell code to fetch and report the audit records:

[array]$Operations = "RestrictContentOrgWideSearchDisabled", "RestrictContentOrgWideSearchEnabled", "SharePointRCDUpdateJustification"
[array]$Records = Search-UnifiedAuditLog -StartDate (Get-Date).AddDays(-1) -EndDate (Get-Date) -Formatted `
    -SessionCommand ReturnLargeSet -ResultSize 5000 -Operations $Operations
$Records = $Records | Sort-Object Identity -Unique

$Report = [System.Collections.Generic.List[Object]]::new()
ForEach ($Rec in $Records) {
    $AuditData = $Rec.AuditData | ConvertFrom-Json
 
    Switch ($AuditData.Operation) {
        "RestrictContentOrgWideSearchEnabled" {
            $Action = ("Enabled RCD for {0}" -f $AuditData.ObjectId)
        }
        "SharePointRCDUpdateJustification" {
            $Action = ("RCD Justification: {0}" -f $AuditData.RCDJustification)
        }
        "RestrictContentOrgWideSearchDisabled" {
            $Action = ("Disabled RCD for {0}" -f $AuditData.ObjectId)
        }
        Default {
            $Action = $AuditData.Operation
        }
    }
    $ReportLine = [PSCustomObject][Ordered]@{
        TimeStamp       = Get-Date ($AuditData.CreationTime) -format 'dd-MMM-yyyy HH:mm'
        User            = $AuditData.UserId
        Action          = $AuditData.Operation
        SiteURL         = $AuditData.ObjectId
        EventInfo       = $Action

    }
    $Report.Add($ReportLine)
}
$Report = $Report | Sort-Object {$_.TimeStamp -as [datetime]} -Descending
$Report | Out-GridView -Title "Restricted Content Discovery Audit Records"

A Natural Evolution

It’s natural and good that Microsoft should augment tenant administrator control over RCD with site-level control. Site administrators tend to understand better than anyone else what kind of content is stored in the sites that they manage, so they’re best positioned to make the decision whether Microsoft 365 Copilot should be allowed to use that content.

Insight like this doesn’t come easily. You’ve got to know the technology and understand how to look behind the scenes. Benefit from the knowledge and experience of the Office 365 for IT Pros team by subscribing to the best eBook covering Office 365 and the wider Microsoft 365 ecosystem.