Track Restored Users in Microsoft 365 Using Graph PowerShell

Restoring deleted user accounts in Microsoft 365 is a critical operation, especially in scenarios involving accidental deletions or user reactivations. Keeping track of such events helps IT administrators maintain visibility and auditability within the tenant. This article walks you through a Graph PowerShell script that retrieves all restored users from Microsoft 365 audit logs — along with who restored them, when, and the result of the action.

The Script

# Connect to Microsoft Graph with required scopes
Connect-MgGraph -Scopes "AuditLog.Read.All", "User.Read.All"
                                
# Set the time window for the audit log query (last 30 days max allowed)
$startDate = (Get-Date).AddDays(-30).ToString("yyyy-MM-ddTHH:mm:ssZ")
                                
# Fetch all 'Restore user' audit events
$restoredUsers = Get-MgAuditLogDirectoryAudit -Filter "activityDisplayName eq 'Restore user' and activityDateTime ge $startDate" -All
                                
# Parse and display results
$results = foreach ($log in $restoredUsers) {
    [PSCustomObject]@{
        "Restored Time"       = ($log.ActivityDateTime).ToLocalTime()
        "Restored User (UPN)" = $log.TargetResources[0].UserPrincipalName
        "Restored By (UPN)"   = $log.InitiatedBy.User.UserPrincipalName
        "Result"              = if ($log.Result -eq "success") { "Success" } else { "Failure" }
    }
}
                                
# Display the output in a table format
$results | Format-Table -AutoSize
                                

How the Script Works

This PowerShell script does the following:

• Connects to Microsoft Graph using the required delegated scopes:
• AuditLog.Read.All
• User.Read.All
• Sets a 30-day lookback window, since Graph API retains audit logs for a maximum of 30 days.
• Filters the audit logs using:
• activityDisplayName eq 'Restore user'
• activityDateTime filter to limit by date.
• Extracts key fields from the logs:
• ActivityDateTime: When the restore happened.
• TargetResources[0].UserPrincipalName: The UPN of the restored user.
• InitiatedBy.User.UserPrincipalName: The admin who performed the action.
• Result: Whether the operation was a success or failure.
• Displays the results in a clean, readable table.

Further Enhancements

You can take this script a step further with the following enhancements:

• Export to CSV for reporting or archiving:

$results | Export-Csv -Path "RestoredUsersReport.csv" -NoTypeInformation

• Make date range dynamic (via user input or parameters).
• Send results via email to IT teams for daily/weekly reporting.
• Schedule the script via Task Scheduler or Azure Automation for continuous monitoring.

Use Cases

• Security & Compliance Audits – Track who restored which users and when, for compliance and investigation purposes.
• Change Management – Maintain transparency over directory-level changes made by IT administrators.
• User Lifecycle Monitoring –Understand and log user account recovery patterns to optimize account handling.
• Forensic Investigations – In case of security incidents, determine whether any deleted accounts were quietly restored.

Possible Errors & Solutions

Error	Cause	Solution
Access Denied	Missing required Graph scopes	Ensure the account has AuditLog.Read.All and User.Read.All permissions. Use Connect-MgGraph -Scopes "AuditLog.Read.All", "User.Read.All"
audit logs return no data	No 'Restore user' events in past 30 days	Verify if any users were restored recently. Try adjusting the date range.
TargetResources[0].UserPrincipalName is null	The log record lacks expected fields	Add null checks or use DisplayName as fallback: $log.TargetResources[0].DisplayName
CommandNotFoundException	Graph module not installed	Run Install-Module Microsoft.Graph -Scope CurrentUser before using the script.

Conclusion

Monitoring restored user activity is crucial for any Microsoft 365 environment. With just a few lines of Graph PowerShell, you can gain visibility into who restored a user, when, and whether the action succeeded — helping ensure accountability and compliance.

This script not only empowers IT admins to audit restoration actions easily, but also serves as a base for broader security automation. Try it out, customize it, and integrate it into your monitoring strategy.